rman 1.3.0 → 2.0.0-beta.3

package/core/classes/registry.js

@@ -0,0 +1,47 @@
+/**
+ * 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 class Registry {
+    items = [];
+    /** Contributions in registration order, which for a plugin is `plugins` declaration order. */
+    get all() {
+        return this.items;
+    }
+    get size() {
+        return this.items.length;
+    }
+    /** 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) {
+        if (!this.items.includes(item))
+            this.items.push(item);
+        return 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(ask) {
+        for (const item of this.items) {
+            const answer = ask(item);
+            if (answer !== undefined)
+                return answer;
+        }
+        return undefined;
+    }
+    [Symbol.iterator]() {
+        return this.items[Symbol.iterator]();
+    }
+}

package/core/{repository.d.ts → classes/repository.d.ts}

@@ -1,6 +1,8 @@
-import { type ConfigScope, type GitScope, type PackageScope, type RepositoryScope } from './config.js';
-import type { LoadedCommand } from './custom-command.js';
+import { type ConfigScope, type GitScope, type PackageScope, type RepositoryScope } from '../../interfaces/config-scope.interface.js';
+import { RmanApplication } from '../application.js';
+import type { Platform } from '../interfaces/plugin.js';
 import { Package } from './package.js';
+import { Workspace } from './workspace.js';
 export declare class Repository extends Package {
     readonly dirname: string;
     readonly monorepo: boolean;
@@ -12,7 +14,6 @@ export declare class Repository extends Package {
     readonly rootPackage: Package;
     /** Commands the repository's plugins contributed, loaded during `create` because the workspace
      *  providers they bring are needed before any package can be found. `cli.ts` registers them. */
-    pluginCommands: LoadedCommand[];
     /**
      * Cached repository scope - see `_repositoryScope`.
      *
@@ -28,19 +29,33 @@ export declare class Repository extends Package {
      *  and because reading it is a subprocess: a deep walk of a package must not spawn one. */
     private _git?;
     /**
-     * Files `${{ read(...) }}` has parsed, shared by every package's scope and keyed by the identity
-     * of the bytes - see `readStructuredFile`.
+     * What `${{ file... }}` and `${{ read(...) }}` answer from, for every package.
      *
-     * **On the repository rather than per scope, and that is the whole point of it**: `configScope`
-     * is built once per package, so a cache living there would re-read a repository-level file once
-     * for every package that mentions it.
+     * **One per repository rather than one per scope, and that is the whole point of it**:
+     * `configScope` is built once per package, so a parse cache living there would re-read a
+     * repository-level file once for every package that mentions it. The cache inside is keyed by the
+     * identity of the bytes (`mtimeNs:size`), because rman writes JSON while it runs - `version`
+     * rewrites every bumped manifest and then re-interpolates its deferred hooks.
      */
-    private readonly _readCache;
-    protected constructor(dirname: string, monorepo: boolean, packages: Package[], 
+    private readonly _files;
+    /**
+     * The application this repository belongs to - its services, its technologies, its logger.
+     *
+     * **Non-enumerable**, like `_repoScope` and `_git` beside it: the two things that walk a
+     * repository are `{...pkg}` spreads and the config scope, and an enumerable back-reference to the
+     * whole application would be dragged into both. A `Package` deliberately has no such field at
+     * all; a repository is never spread or serialized, which is what makes this one safe - measured,
+     * rather than assumed.
+     */
+    readonly app: RmanApplication;
+    protected constructor(app: RmanApplication, dirname: string, monorepo: boolean, packages: Package[], 
     /** The directory `Repository.create()` was actually invoked from - unlike `dirname` (the
      *  resolved repository root, possibly several levels up), this is where the user's shell
      *  really was. Used by `currentPackage` to scope commands to "the package I'm standing in". */
-    cwd?: string);
+    cwd?: string, 
+    /** The root directory's own technology, from the same walk that found the packages - so the
+     *  repository and its `rootPackage` agree without either searching the registry again. */
+    platform?: Platform);
     /**
      * The package whose own directory contains `cwd` (the deepest match, so a package nested
      * inside another's directory resolves to the innermost one) - or `undefined` when `cwd` *is*
@@ -60,9 +75,21 @@ export declare class Repository extends Package {
      * dirty, the reference point decides the rest: without `hash`, `committed`
      * means committed but not yet in the upstream branch; with `hash`, `changed`
      * means it differs from that commit. Otherwise a package is `clean`.
+     *
+     * **Keyed by `Package.selector`**, which is what addresses a package - it was `name`, and the two
+     * coincide wherever a technology names its packages. A repository whose does not had every such
+     * package answering to `""`, so one entry stood for all of them.
+     *
+     * **`includeRoot` is opt-in, and the reason is that the root's answer means something different.**
+     * Its directory contains every other package, so the same rule - "does a changed file fall under
+     * this directory" - reports `dirty` for the root whenever *anything* in the repository is dirty.
+     * That is the honest reading of the rule rather than a bug, and it is not what `run --changed`
+     * wants, so only a caller that asked for the root gets it (`rman list`'s table, which shows the
+     * root as the tree's own row).
      */
     listStatus(options?: {
         hash?: string;
+        includeRoot?: boolean;
     }): Promise<Record<string, Repository.PackageStatus>>;
     /**
      * The scope a `${{ ... }}` expression is evaluated against for `pkg`, optionally with the version
@@ -89,13 +116,29 @@ export declare class Repository extends Package {
      * nothing under `getPackages()` is the root, so only its own unmarked config applies.
      */
     /**
-     * Gives every package its `repository` and `parent`, before any config is resolved - a config
-     * expression or a provider may already want to navigate from a package outwards.
+     * Gives every package its `repository`, and hangs the `parent`/`children` tree off the walk that
+     * found them - before any config is resolved, since a config expression or a provider may already
+     * want to navigate from a package outwards.
+     *
+     * **The containment is read from the tree rather than recomputed from paths.** It used to be an
+     * O(n²) sweep comparing every package's directory against every other's and keeping the longest
+     * prefix - which is the same question `Workspace.walk` answers on the way down, asked again
+     * afterwards with the answer thrown away. Two places deriving one relationship is two places to
+     * disagree; there is one now.
+     *
+     * **`parent` is defined non-enumerably, `children` is a plain field**, which is the one asymmetry
+     * here and it is deliberate: a tree is serialized downwards, so `children` has to be walkable and
+     * `parent` must not be, or every `JSON.stringify` is a cycle. The same way `Repository.app` and
+     * `ORIGINS` travel.
      *
      * A repository's own `repository` is itself, which reads oddly and is the honest answer:
      * `Repository extends Package`, so the repository *is* a package of its own repository.
      */
-    protected _linkPackages(): void;
+    protected _linkPackages(tree: Workspace.Node, nodes: Workspace.Node[], packages: Package[]): void;
+    /**
+     * Bakes every package's config: the raw one the workspace cascaded, with every `${{ }}` and value
+     * function resolved against that package's scope.
+     */
     protected _resolveConfigs(): Promise<void>;
     protected _topoSortPackages(packages: Package[]): void;
     protected _packageScope(pkg: Package, targetVersion?: string): PackageScope;
@@ -131,20 +174,26 @@ export declare class Repository extends Package {
      *    otherwise: the plugins that know what a package is are named in the config file this step
      *    is looking for.
      * 2. **Load the plugins** the root's config names, which registers their workspace providers
-     *    (and their commands, handed on via `pluginCommands` - `cli.ts` registers those).
+     *    (their commands arrive through `.rmanrc "commands"`, which `cli.ts` reads).
      * 3. **Ask the providers** for the layout. None recognizing it means a repository that is itself
      *    the one package.
      *
-     * **A repository whose `.rmanrc` names no plugin has no packages beyond itself**, and that is the
+     * **A repository no technology recognizes has no packages beyond itself**, and that is the
      * boundary working rather than failing: `workspaces` in a `package.json` is npm's idea, so it
-     * takes `plugins: ['rman-node']` to be read as one.
+     * takes a platform that reads one for the directory to be a workspace at all. rman's own presets
+     * are laid under every root (see `DEFAULT_PRESETS`), so a plain Node repository needs no config
+     * file to say so; anything else arrives through `extends` or `platforms`.
      */
     static create(root?: string, options?: {
         deep?: number;
+        app?: RmanApplication;
+        presets?: readonly string[];
     }): Promise<Repository>;
-    /** Finishes constructing `repo` with the async work a constructor can't do itself - resolving
-     *  `.rmanrc`/`.rmanrc.yml`/`.rmanrc.cjs`/`.mjs`/`.js` config (which may need a dynamic `import()`)
-     *  before the dependency graph is built from it. */
+    /**
+     * Takes the workspace's packages as this repository's own - the back-references a `Package` needs
+     * and the parent/child edges the walk established.
+     */
+    protected _adopt(workspace: Workspace): void;
     private static _init;
 }
 export declare namespace Repository {

package/core/{repository.js → classes/repository.js}

@@ -1,11 +1,14 @@
 import { execFileSync } from 'node:child_process';
 import path from 'path';
 import semver from 'semver';
-import { GitHelper } from '../utils/git.js';
-import { createFileScope, createReadScope, DEFERRED_PATHS, interpolateConfig, readDirConfig, resolveConfig, } from './config.js';
-import { Manifest } from './manifest.js';
+import {} from '../../interfaces/config-scope.interface.js';
+import { GitHelper } from '../../utils/git.js';
+import { RmanApplication } from '../application.js';
+import { ConfigFileScope } from '../config/config-file-scope.js';
+import { ConfigInterpolator } from '../config/config-interpolator.js';
+import { DEFERRED_PATHS } from '../config/config-paths.js';
+import { Manifest } from '../interfaces/manifest.js';
 import { Package } from './package.js';
-import { loadPlugins } from './plugin.js';
 import { Workspace } from './workspace.js';
 export class Repository extends Package {
     dirname;
@@ -15,7 +18,6 @@ export class Repository extends Package {
     rootPackage;
     /** Commands the repository's plugins contributed, loaded during `create` because the workspace
      *  providers they bring are needed before any package can be found. `cli.ts` registers them. */
-    pluginCommands = [];
     /**
      * Cached repository scope - see `_repositoryScope`.
      *
@@ -31,25 +33,40 @@ export class Repository extends Package {
      *  and because reading it is a subprocess: a deep walk of a package must not spawn one. */
     _git;
     /**
-     * Files `${{ read(...) }}` has parsed, shared by every package's scope and keyed by the identity
-     * of the bytes - see `readStructuredFile`.
+     * What `${{ file... }}` and `${{ read(...) }}` answer from, for every package.
      *
-     * **On the repository rather than per scope, and that is the whole point of it**: `configScope`
-     * is built once per package, so a cache living there would re-read a repository-level file once
-     * for every package that mentions it.
+     * **One per repository rather than one per scope, and that is the whole point of it**:
+     * `configScope` is built once per package, so a parse cache living there would re-read a
+     * repository-level file once for every package that mentions it. The cache inside is keyed by the
+     * identity of the bytes (`mtimeNs:size`), because rman writes JSON while it runs - `version`
+     * rewrites every bumped manifest and then re-interpolates its deferred hooks.
      */
-    _readCache = new Map();
-    constructor(dirname, monorepo, packages, 
+    _files = new ConfigFileScope();
+    /**
+     * The application this repository belongs to - its services, its technologies, its logger.
+     *
+     * **Non-enumerable**, like `_repoScope` and `_git` beside it: the two things that walk a
+     * repository are `{...pkg}` spreads and the config scope, and an enumerable back-reference to the
+     * whole application would be dragged into both. A `Package` deliberately has no such field at
+     * all; a repository is never spread or serialized, which is what makes this one safe - measured,
+     * rather than assumed.
+     */
+    app;
+    constructor(app, dirname, monorepo, packages, 
     /** The directory `Repository.create()` was actually invoked from - unlike `dirname` (the
      *  resolved repository root, possibly several levels up), this is where the user's shell
      *  really was. Used by `currentPackage` to scope commands to "the package I'm standing in". */
-    cwd = dirname) {
-        super(dirname);
+    cwd = dirname, 
+    /** The root directory's own technology, from the same walk that found the packages - so the
+     *  repository and its `rootPackage` agree without either searching the registry again. */
+    platform) {
+        super(dirname, app, platform);
         this.dirname = dirname;
         this.monorepo = monorepo;
         this.packages = packages;
         this.cwd = cwd;
-        this.rootPackage = new Package(dirname);
+        Object.defineProperty(this, 'app', { value: app, enumerable: false, writable: false });
+        this.rootPackage = new Package(dirname, app, platform);
         if (!monorepo)
             this.packages = [this.rootPackage];
         // Config resolution can load a `.rmanrc.cjs`/`.mjs`/`.js` module (dynamic `import()`, always
@@ -94,11 +111,22 @@ export class Repository extends Package {
      * dirty, the reference point decides the rest: without `hash`, `committed`
      * means committed but not yet in the upstream branch; with `hash`, `changed`
      * means it differs from that commit. Otherwise a package is `clean`.
+     *
+     * **Keyed by `Package.selector`**, which is what addresses a package - it was `name`, and the two
+     * coincide wherever a technology names its packages. A repository whose does not had every such
+     * package answering to `""`, so one entry stood for all of them.
+     *
+     * **`includeRoot` is opt-in, and the reason is that the root's answer means something different.**
+     * Its directory contains every other package, so the same rule - "does a changed file fall under
+     * this directory" - reports `dirty` for the root whenever *anything* in the repository is dirty.
+     * That is the honest reading of the rule rather than a bug, and it is not what `run --changed`
+     * wants, so only a caller that asked for the root gets it (`rman list`'s table, which shows the
+     * root as the tree's own row).
      */
     async listStatus(options) {
         const hash = options?.hash;
         const git = new GitHelper({ cwd: this.dirname });
-        const packages = this.getPackages();
+        const packages = options?.includeRoot ? [this.rootPackage, ...this.getPackages()] : this.getPackages();
         const belongsTo = (p, files) => files.some(f => !path.relative(p.dirname, f).startsWith('..'));
         const [dirtyFiles, referenceFiles] = await Promise.all([
             git.listDirtyFiles({ absolute: true }),
@@ -107,11 +135,11 @@ export class Repository extends Package {
         const result = {};
         for (const p of packages) {
             if (belongsTo(p, dirtyFiles))
-                result[p.name] = 'dirty';
+                result[p.selector] = 'dirty';
             else if (belongsTo(p, referenceFiles))
-                result[p.name] = hash ? 'changed' : 'committed';
+                result[p.selector] = hash ? 'changed' : 'committed';
             else
-                result[p.name] = 'clean';
+                result[p.selector] = 'clean';
         }
         return result;
     }
@@ -131,10 +159,10 @@ export class Repository extends Package {
             repository: this._repositoryScope(),
             /** `pkg.dirname`, not the repository root: a `"[*]"` block asking whether
              *  `tsconfig-build.json` exists has to be answered per package. */
-            file: createFileScope(pkg.dirname),
+            file: this._files.fileScope(pkg.dirname),
             /** Same base directory as `file`, so one `"[*]"` declaration reads each package's own copy -
              *  and the cache is the repository's, so a file they *share* is parsed once. */
-            read: createReadScope(pkg.dirname, this._readCache),
+            read: this._files.readScope(pkg.dirname),
             env: { ...process.env },
             semver,
             path,
@@ -173,52 +201,71 @@ export class Repository extends Package {
      * nothing under `getPackages()` is the root, so only its own unmarked config applies.
      */
     /**
-     * Gives every package its `repository` and `parent`, before any config is resolved - a config
-     * expression or a provider may already want to navigate from a package outwards.
+     * Gives every package its `repository`, and hangs the `parent`/`children` tree off the walk that
+     * found them - before any config is resolved, since a config expression or a provider may already
+     * want to navigate from a package outwards.
+     *
+     * **The containment is read from the tree rather than recomputed from paths.** It used to be an
+     * O(n²) sweep comparing every package's directory against every other's and keeping the longest
+     * prefix - which is the same question `Workspace.walk` answers on the way down, asked again
+     * afterwards with the answer thrown away. Two places deriving one relationship is two places to
+     * disagree; there is one now.
+     *
+     * **`parent` is defined non-enumerably, `children` is a plain field**, which is the one asymmetry
+     * here and it is deliberate: a tree is serialized downwards, so `children` has to be walkable and
+     * `parent` must not be, or every `JSON.stringify` is a cycle. The same way `Repository.app` and
+     * `ORIGINS` travel.
      *
      * A repository's own `repository` is itself, which reads oddly and is the honest answer:
      * `Repository extends Package`, so the repository *is* a package of its own repository.
      */
-    _linkPackages() {
-        this.repository = this;
-        this.rootPackage.repository = this;
-        for (const pkg of this.packages) {
-            pkg.repository = this;
-            /** The deepest package that strictly contains it - the root for an ordinary member, an
-             *  enclosing package for a nested one. Longest containing path wins, the same rule
-             *  `currentPackage` uses to resolve "the package I am standing in". */
-            let parent = this.monorepo ? this.rootPackage : undefined;
-            for (const other of this.packages) {
-                if (other === pkg)
-                    continue;
-                const rel = path.relative(other.dirname, pkg.dirname);
-                const contains = !!rel && !rel.startsWith('..') && !path.isAbsolute(rel);
-                if (contains && (!parent || other.dirname.length > parent.dirname.length))
-                    parent = other;
+    _linkPackages(tree, nodes, packages) {
+        /** Non-enumerable everywhere, including on the repository itself - see `Package.repository`.
+         *  `writable` because `import` grafts an external repository's packages onto this one. */
+        const link = (pkg) => {
+            Object.defineProperty(pkg, 'repository', { value: this, enumerable: false, configurable: true, writable: true });
+        };
+        link(this);
+        link(this.rootPackage);
+        for (const pkg of this.packages)
+            link(pkg);
+        /** The walk visits a directory once, so one node is one package and this map is a bijection -
+         *  which is what lets the edges below be read off the tree instead of guessed from paths. */
+        const byNode = new Map(nodes.map((node, i) => [node, packages[i]]));
+        byNode.set(tree, this.rootPackage);
+        for (const node of [tree, ...nodes]) {
+            const pkg = byNode.get(node);
+            for (const childNode of node.children) {
+                const child = byNode.get(childNode);
+                pkg.children.push(child);
+                Object.defineProperty(child, 'parent', { value: pkg, enumerable: false, configurable: true });
             }
-            pkg.parent = pkg === this.rootPackage ? undefined : parent;
         }
+        /** `Repository extends Package` while holding a separate `rootPackage` for the same directory,
+         *  so both are truthfully the root - they share the one array rather than each getting a copy
+         *  that could drift. */
+        Object.defineProperty(this, 'children', { value: this.rootPackage.children, enumerable: true });
     }
+    /**
+     * Bakes every package's config: the raw one the workspace cascaded, with every `${{ }}` and value
+     * function resolved against that package's scope.
+     */
+    /* **The one step the workspace deliberately stops short of.** Resolving an expression needs
+     * `pkg`, `repository`, `file` and `git` - which belong to a repository rather than to its layout,
+     * and `configScope` is where the measured subtleties of building that scope live.
+     *
+     * `DEFERRED_PATHS` are left raw, so the resolved config is the only copy anyone needs - `version`
+     * reads its own hooks straight off it and interpolates them once `pkg.targetVersion` exists. */
     async _resolveConfigs() {
-        const cache = new Map();
-        /**
-         * `DEFERRED_PATHS` are left *raw* in the result (see `interpolateConfig`'s `walk`), so the
-         * resolved config is the only copy anyone needs - `version` reads its own hooks straight off
-         * `config` and interpolates them itself once `pkg.targetVersion` exists. There used to be a
-         * second `rawConfig` copy of every package's config for that one reader; measured identical.
-         */
-        /**
-         * The root is resolved **with its name**, like every other package. Not because a glob could
-         * match it - `"[*]"` and every other name pattern speak only to the packages below - but because
-         * `resolveConfig` needs a name to run `matchingSelectors` at all, and `"[/]"` is a selector.
-         * Passing none would silently drop the root's own block.
-         */
-        const rootRaw = await resolveConfig(this.dirname, this.dirname, cache, this.rootPackage.name);
-        this.config = interpolateConfig(rootRaw, this.configScope(this.rootPackage), { skip: DEFERRED_PATHS });
-        for (const pkg of this.packages) {
-            const raw = await resolveConfig(this.dirname, pkg.dirname, cache, pkg.name);
-            pkg.config = interpolateConfig(raw, this.configScope(pkg), { skip: DEFERRED_PATHS });
-        }
+        const interpolator = new ConfigInterpolator();
+        const bake = (pkg) => interpolator.interpolate({
+            config: pkg.rawConfig,
+            scope: this.configScope(pkg),
+            skip: DEFERRED_PATHS,
+        });
+        this.config = bake(this.rootPackage);
+        for (const pkg of this.packages)
+            pkg.config = bake(pkg);
         if (this.monorepo)
             this.rootPackage.config = this.config;
     }
@@ -236,7 +283,7 @@ export class Repository extends Package {
         // than refusing it - so the scope has to survive one too.
         const name = pkg.name ?? '';
         /** Splitting `@scope/name` is npm's convention, not a universal - the provider decides. */
-        const { scope: nameScope, unscopedName } = Manifest.splitName(pkg.dirname, name);
+        const { scope: nameScope, unscopedName } = Manifest.splitName(this.app, pkg.dirname, name);
         const scope = {
             name,
             scope: nameScope,
@@ -384,34 +431,107 @@ export class Repository extends Package {
      *    otherwise: the plugins that know what a package is are named in the config file this step
      *    is looking for.
      * 2. **Load the plugins** the root's config names, which registers their workspace providers
-     *    (and their commands, handed on via `pluginCommands` - `cli.ts` registers those).
+     *    (their commands arrive through `.rmanrc "commands"`, which `cli.ts` reads).
      * 3. **Ask the providers** for the layout. None recognizing it means a repository that is itself
      *    the one package.
      *
-     * **A repository whose `.rmanrc` names no plugin has no packages beyond itself**, and that is the
+     * **A repository no technology recognizes has no packages beyond itself**, and that is the
      * boundary working rather than failing: `workspaces` in a `package.json` is npm's idea, so it
-     * takes `plugins: ['rman-node']` to be read as one.
+     * takes a platform that reads one for the directory to be a workspace at all. rman's own presets
+     * are laid under every root (see `DEFAULT_PRESETS`), so a plain Node repository needs no config
+     * file to say so; anything else arrives through `extends` or `platforms`.
      */
+    /* **`presets` is an opt-out, and it exists for the specs that must not have one.** rman's own
+     * presets are laid under every root, so a caller that brought its own ecosystem would otherwise
+     * get the `node` technology, `clean`, `ci` and the npm publish target beside it. That is right
+     * for a repository and wrong for a synthetic one: measured, the core's `publish` specs ran a
+     * **real `npm publish` against registry.npmjs.org**, and only a 404 stopped it - the failure
+     * `useLocalBin`'s doc already records for `docker`, arriving by a new route. `test/_fixture.ts`
+     * passes `[]`. */
     static async create(root, options) {
         const from = root || process.cwd();
         const rootDir = Workspace.findRoot(from, options?.deep ?? 10);
-        /** The root's own config, raw: `plugins` is a list of package names, so it needs neither the
-         *  package list (which does not exist yet) nor expression interpolation. */
-        const rootConfig = await readDirConfig(rootDir);
-        const pluginCommands = await loadPlugins(rootDir, rootConfig);
-        const layout = Workspace.resolve(rootDir);
-        const packages = (layout?.packageDirs ?? []).map(dir => new Package(dir));
-        const repo = new Repository(layout?.root ?? rootDir, packages.length > 0, packages, from);
-        repo.pluginCommands = pluginCommands;
-        repo._linkPackages();
+        const app = options?.app ?? new RmanApplication();
+        /**
+         * **The whole of discovery and config reading is the workspace's.** It reads each level's
+         * config, loads whatever that level names, decides which technology claims each directory,
+         * assigns the selectors and cascades every package's **raw** config.
+         *
+         * Technologies already on the application are handed over: a programmatic caller - and every
+         * spec in this suite - registers one without writing a config, and the walk has to see it.
+         */
+        const workspace = await Workspace.create(rootDir, {
+            app,
+            deep: options?.deep,
+            platforms: [...app.platforms],
+            presets: options?.presets,
+        });
+        /** What the configs named, onto the application the commands read from. */
+        for (const platform of workspace.platforms)
+            app.platforms.add(platform);
+        for (const plugin of workspace.plugins) {
+            app.plugins.add(plugin);
+            await plugin.afterInitApplication?.({ app });
+        }
+        /** One loop, because `workspace.platforms` already holds every technology in play whatever
+         *  route it arrived by. There used to be a second one over each plugin's own `platforms`, and
+         *  by the end it was pure duplication of this. */
+        for (const platform of workspace.platforms) {
+            if (platform.versionPlanner)
+                app.versionPlanner = platform.versionPlanner;
+        }
+        /** **Publish targets the root config declared.** `publish` builds its `--target` choices from
+         *  `app.publishTargets` when its factory runs, so they have to be there before the commands
+         *  are. Read off the root's own level rather than a package's: a target is the repository's. */
+        for (const target of toList(workspace.rootPackage.rawConfig.publishTargets)) {
+            if (!target || typeof target !== 'object' || typeof target.name !== 'string') {
+                throw new Error(`"publishTargets" takes a target or a glob naming modules that export one - got ` +
+                    `${target === null ? 'null' : typeof target}.`);
+            }
+            app.publishTargets.add(target);
+        }
+        const packages = workspace.packages;
+        const repo = new Repository(app, rootDir, packages.length > 0, packages, from, workspace.rootPackage.platform);
+        repo._adopt(workspace);
+        app.attachRepository(repo);
         return Repository._init(repo);
     }
-    /** Finishes constructing `repo` with the async work a constructor can't do itself - resolving
-     *  `.rmanrc`/`.rmanrc.yml`/`.rmanrc.cjs`/`.mjs`/`.js` config (which may need a dynamic `import()`)
-     *  before the dependency graph is built from it. */
+    /**
+     * Takes the workspace's packages as this repository's own - the back-references a `Package` needs
+     * and the parent/child edges the walk established.
+     */
+    /* `Repository extends Package` while the workspace built its own root package for the same
+     * directory, so both are, truthfully, the root. This keeps the workspace's - it is the one the
+     * walk handed a platform and a selector - and leaves `Repository` itself pointing at the same
+     * children. */
+    _adopt(workspace) {
+        const link = (pkg) => void Object.defineProperty(pkg, 'repository', {
+            value: this,
+            enumerable: false,
+            configurable: true,
+            writable: true,
+        });
+        link(this);
+        this.rootPackage = workspace.rootPackage;
+        link(this.rootPackage);
+        for (const pkg of this.packages)
+            link(pkg);
+        if (!this.monorepo)
+            this.packages = [this.rootPackage];
+        Object.defineProperty(this, 'children', { value: this.rootPackage.children, enumerable: true });
+    }
     static async _init(repo) {
         await repo._resolveConfigs();
         repo._updateDependencies();
+        /** **Last, and that is the whole point of the second stage.** Every package is found, every
+         *  config is baked and the dependency graph is linked - so a plugin handed this repository can
+         *  read it rather than being told to wait for a command it may not contribute. */
+        for (const plugin of repo.app.plugins)
+            await plugin.afterInitRepository?.({ app: repo.app, repository: repo });
         return repo;
     }
 }
+/** A key that takes one value or a list of them, as a list. */
+function toList(value) {
+    return value === undefined ? [] : Array.isArray(value) ? value : [value];
+}

package/core/classes/service.d.ts

@@ -0,0 +1,49 @@
+import type { Logger } from '../../utils/logger.js';
+import type { RmanApplication } from '../application.js';
+import type { Repository } from './repository.js';
+/**
+ * **The one service shape.** Everything that does work on a repository is a class extending this,
+ * constructed once per `RmanApplication` and reached through `app.getService(name)`.
+ *
+ * rman's services were `export namespace` blocks, and the split between those and the two classes
+ * (`VersionPlanService`, `VersionScheme`) was historical rather than principled: whatever needed to
+ * be *extended* became a class, and the rest stayed a namespace. Three consequences, all of them
+ * measured in this repository:
+ *
+ * - **A namespace that needs state can only have global state.** `RunService` is a namespace and
+ *   acquired three module-level variables - `stepSources` and two "already warned" sets - which is
+ *   why a warning printed for one repository was suppressed for the next one in the same process.
+ * - **A namespace cannot be extended.** The two seams a plugin has to specialize
+ *   (`NodeVersionPlanService extends VersionPlanService`) are precisely the two that are classes.
+ * - **A namespace has to be stubbed by mutating the module**, and CLAUDE.md records that failing:
+ *   a spec that captured a core function at module scope and restored it put the *un-augmented*
+ *   version back for the rest of the process and broke a spec two files away. An instance is
+ *   rebuilt per application, so a stub dies with it.
+ *
+ * **`repository` is no longer a parameter.** Nearly every service method took it first; it now
+ * comes from the application, which is what made the argument redundant in the first place.
+ *
+ * Pure functions of their arguments stay plain exported functions rather than becoming services -
+ * `ConventionalCommitsService.parseSubject('feat: x')` parses a string and will never hold state,
+ * and making it `app.getService('conventionalCommits').parseSubject(...)` would be ceremony that
+ * also puts an application between a caller and a parser. The line is whether it needs the
+ * repository.
+ */
+export declare abstract class Service {
+    protected readonly app: RmanApplication;
+    constructor(app: RmanApplication);
+    protected get repository(): Repository;
+    protected get logger(): Logger;
+}
+/**
+ * Every service the application can hand out, by name.
+ *
+ * Declaration-merged, like `RmanConfigKeys`: the core declares its own here, and a plugin adds its
+ * own from its own package with `declare module 'rman'`. That is what keeps `getService` typed -
+ * a bare `Map<string, Service>` would need a cast at every call and would turn a misspelled name
+ * into a runtime failure instead of a compile error.
+ */
+export interface ServiceMap {
+}
+/** How a service is built when the application first needs it. */
+export type ServiceFactory<T> = (app: RmanApplication) => T;