rman 1.3.0 → 2.0.0-beta.2

package/plugins/node/services/publish.service.js

@@ -0,0 +1,371 @@
+/**
+ * Prepares the `package.json` that `npm publish` will actually read, and returns a function that
+ * undoes it - always call that from a `finally`, so a failed publish leaves nothing behind.
+ *
+ * Which file that is depends on where the output lives:
+ *
+ * - **Publishing the package directory itself** - its own `package.json` is the manifest, rewritten
+ *   in place: every `"workspace:"` range becomes a real, registry-consumable one (the same
+ *   substitution pnpm/yarn's own publish performs - see `resolveWorkspaceRange`), since `npm
+ *   publish` reads what is on disk rather than packing from a staging tarball.
+ * - **Publishing a build directory** - there is no manifest there until something writes one, and
+ *   that something is this: see `derivePublishManifest`.
+ *
+ * Returns `undefined` when there is nothing to do at all (the package directory, with no
+ * `"workspace:"` range in it) - no disk write, nothing to restore.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { exec } from '../../../utils/exec.js';
+import { GitHelper } from '../../../utils/git.js';
+import { filterPackages } from '../../../utils/package-filter.js';
+import { isCalendarVersion } from '../../../utils/release-version.js';
+import { DEPENDENCY_KEYS } from '../node-manifest.provider.js';
+import { npmViewPackage } from '../utils/npm-view.js';
+import { parseWorkspaceRange, resolveWorkspaceRange } from '../utils/workspace-range.js';
+import { CiService } from './ci.service.js';
+function preparePublishManifest(pkg, publishDir, packagesByName) {
+    if (path.resolve(publishDir) !== path.resolve(pkg.dirname)) {
+        const file = path.join(publishDir, 'package.json');
+        const previous = fs.existsSync(file) ? fs.readFileSync(file, 'utf-8') : undefined;
+        fs.mkdirSync(publishDir, { recursive: true });
+        fs.writeFileSync(file, JSON.stringify(derivePublishManifest(pkg, packagesByName), undefined, 2) + '\n', 'utf-8');
+        return () => {
+            if (previous === undefined)
+                fs.rmSync(file, { force: true });
+            else
+                fs.writeFileSync(file, previous, 'utf-8');
+        };
+    }
+    const hasWorkspaceRange = DEPENDENCY_KEYS.some(depKey => {
+        const deps = pkg.manifest.raw[depKey];
+        return deps && Object.values(deps).some(v => parseWorkspaceRange(v));
+    });
+    if (!hasWorkspaceRange)
+        return undefined;
+    /** The file's exact bytes, not a re-serialization: this is restored verbatim afterwards, so a
+     *  round-trip through `JSON.stringify` would rewrite the author's formatting as a side effect of
+     *  publishing. */
+    const original = fs.readFileSync(pkg.manifestFileName, 'utf-8');
+    resolveWorkspaceRanges(pkg.manifest.raw, packagesByName);
+    pkg.writeManifest();
+    return () => {
+        fs.writeFileSync(pkg.manifestFileName, original, 'utf-8');
+        pkg.reloadManifest();
+    };
+}
+/**
+ * The manifest to publish from a build directory, derived from the package's own - generated here
+ * rather than by a build script, and deliberately with nothing to configure.
+ *
+ * Generated at *publish* time, which is the whole point: a build script writes it when the build
+ * runs, so bumping the version afterwards (or building before a bump) publishes a manifest that
+ * disagrees with the package - and the `"workspace:"` rewrite above, which only ever touched the
+ * package's own file, never reached the copy at all.
+ *
+ * What comes out is the package's `package.json` minus what a consumer of the tarball can neither
+ * see nor use:
+ *
+ * - `devDependencies` - npm never installs a dependency's own, so they are pure noise.
+ * - `scripts`, **except** `preinstall`/`install`/`postinstall`. Those three are the only ones a
+ *   consumer's install actually runs, and dropping them would silently break every package that
+ *   builds a native module on install. The rest (`build`, `test`, `prepare`, ...) never reach the
+ *   consumer - `prepare` runs for a git dependency, which builds from the repository, not from this
+ *   tarball.
+ * - `private` - rman refuses to publish a private package in the first place, so carrying the flag
+ *   into a manifest that is being published can only be wrong.
+ * - `publishConfig.directory` - it pointed *here*; kept, it would point one level deeper again.
+ */
+function derivePublishManifest(pkg, packagesByName) {
+    const json = structuredClone(pkg.manifest.raw);
+    resolveWorkspaceRanges(json, packagesByName);
+    delete json.devDependencies;
+    delete json.private;
+    if (json.scripts) {
+        const kept = Object.fromEntries(Object.entries(json.scripts).filter(([name]) => CONSUMER_SCRIPTS.has(name)));
+        if (Object.keys(kept).length)
+            json.scripts = kept;
+        else
+            delete json.scripts;
+    }
+    if (json.publishConfig) {
+        delete json.publishConfig.directory;
+        if (!Object.keys(json.publishConfig).length)
+            delete json.publishConfig;
+    }
+    return json;
+}
+/** The only lifecycle scripts a consumer's `npm install` of this package runs - see
+ *  https://docs.npmjs.com/cli/using-npm/scripts. */
+const CONSUMER_SCRIPTS = new Set(['preinstall', 'install', 'postinstall']);
+/** Rewrites `json`'s `"workspace:"` ranges in place, resolving each against the in-repo package it
+ *  names. Shared by both manifest paths, so they can never disagree about the substitution. */
+function resolveWorkspaceRanges(json, packagesByName) {
+    for (const depKey of DEPENDENCY_KEYS) {
+        const deps = json[depKey];
+        if (!deps)
+            continue;
+        for (const depName of Object.keys(deps)) {
+            const parsed = parseWorkspaceRange(deps[depName]);
+            if (!parsed)
+                continue;
+            const depPkg = packagesByName.get(depName);
+            if (depPkg)
+                deps[depName] = resolveWorkspaceRange(parsed, depPkg.version);
+        }
+    }
+}
+export var PublishService;
+(function (PublishService) {
+    /**
+     * Computes what `publish` *would* do, across every non-private package (topological order,
+     * dependencies before dependents) - never touches the registry to publish anything, just
+     * queries it to decide, so it's safe to call any time, including as the plan a bare `rman
+     * publish` shows before asking for confirmation.
+     *
+     * A `private: true` package is always `'skip'`ped outright. Each remaining package's **dist-tag**
+     * is settled next (`distTagFor`): usually derived from the version itself, `'error'` in the two
+     * cases with nothing to derive - that one is about the invocation rather than the package, so it
+     * is answered before anything touches the network. A package with uncommitted local changes is
+     * `'error'` too (aborts the whole plan) unless `options.ignoreDirty` downgrades it to `'skip'`
+     * instead - same rule `version` uses, since publishing untracked local edits is worse than a bad
+     * commit.
+     *
+     * Otherwise the registry decides, via one `npmViewPackage` per remaining package (run
+     * concurrently): **the local version being among the published `versions`** is `'up-to-date'`,
+     * anything else - including never having been published at all - is `'publish'`. Deliberately not
+     * a comparison against `latest`, which answers a different question and disagrees with this one
+     * the moment a prerelease ships under its own dist-tag; see `npmViewPackage`.
+     *
+     * Deliberately decoupled from `version`: this only ever looks at what's *currently* on disk and
+     * on the registry, never at whether `version` was just run - so it works equally well right
+     * after a version bump, or standing alone in a release pipeline that bumped days earlier.
+     *
+     * A monorepo's root package is never a candidate at all - `repository.getPackages()` already
+     * excludes it for a real monorepo (it only doubles as "the" package in a single-package repo,
+     * where it's a normal candidate like any other).
+     */
+    async function getPlan(repository, options = {}, deps = {}) {
+        const git = new GitHelper({ cwd: repository.dirname });
+        const packages = filterPackages(repository.getPackages({ toposort: true }), options);
+        const dirtyFiles = await git.listDirtyFiles({ absolute: true });
+        const isDirty = (pkg) => dirtyFiles.some(f => !path.relative(pkg.dirname, f).startsWith('..'));
+        const viewPackage = deps.npmViewPackage ?? ((name, cwd) => npmViewPackage(name, cwd, options));
+        const entries = new Map();
+        const toCheck = [];
+        for (const pkg of packages) {
+            /** Asked before the registry is, because it is about the *invocation* rather than the
+             *  package: a prerelease heading for `latest` is wrong whatever the registry says, and
+             *  finding that out after a round trip per package would be a slower way to the same
+             *  refusal. */
+            const distTag = distTagFor(pkg, options.tag);
+            if (retiredDirectoryKey(pkg)) {
+                entries.set(pkg.name, {
+                    package: pkg,
+                    version: pkg.version,
+                    status: 'error',
+                    reason: '.rmanrc "publish.directory" is now "publish.npm.directory" - see the npm publish target',
+                });
+            }
+            else if (pkg.config.publish?.skip) {
+                entries.set(pkg.name, {
+                    package: pkg,
+                    version: pkg.version,
+                    status: 'skip',
+                    reason: 'excluded via .rmanrc "publish.skip"',
+                });
+            }
+            else if (pkg.isPrivate) {
+                entries.set(pkg.name, { package: pkg, version: pkg.version, status: 'skip', reason: 'private package' });
+            }
+            else if (distTag.error) {
+                entries.set(pkg.name, { package: pkg, version: pkg.version, status: 'error', reason: distTag.error });
+            }
+            else if (isDirty(pkg)) {
+                entries.set(pkg.name, {
+                    package: pkg,
+                    version: pkg.version,
+                    status: options.ignoreDirty ? 'skip' : 'error',
+                    reason: 'uncommitted local changes',
+                });
+            }
+            else {
+                toCheck.push(pkg);
+            }
+        }
+        await Promise.all(toCheck.map(async (pkg) => {
+            const view = await viewPackage(pkg.name, pkg.dirname);
+            const registryVersion = view?.latest;
+            /** **This version**, not `latest` - the two part company the moment a prerelease is
+             *  published under its own dist-tag, and `latest` then never moves however many betas go
+             *  out. Asking it kept proposing an already-published version until npm answered 403. */
+            const published = !!view?.versions.includes(pkg.version);
+            const distTag = distTagFor(pkg, options.tag).tag;
+            entries.set(pkg.name, {
+                package: pkg,
+                version: pkg.version,
+                registryVersion,
+                distTag,
+                /** Printed beside the package in the plan, so where a version is going is something the
+                 *  reader confirms rather than something they have to infer from the version string. */
+                detail: distTag ? `-> dist-tag "${distTag}"` : undefined,
+                status: published ? 'up-to-date' : 'publish',
+                reason: published
+                    ? `registry already has ${pkg.version}`
+                    : registryVersion
+                        ? `registry has ${registryVersion}`
+                        : 'never published',
+            });
+        }));
+        return packages.map(pkg => entries.get(pkg.name));
+    }
+    PublishService.getPlan = getPlan;
+    /**
+     * Publishes every `'publish'` entry in `plan`, topological order (already `plan`'s own order -
+     * see `getPlan`), via the configured `packageManager`'s own `publish` command. Sequential, not
+     * concurrent: unlike `run`/`build`, a package genuinely needs its own dependencies to have
+     * landed on the registry first, and publishing is rare enough (once per release) that the
+     * simplicity is worth more than the parallelism `run` gets from `power-tasks`.
+     *
+     * If a package fails, every other still-pending entry depending on it (transitively) is marked
+     * `'error'` too and never attempted - publishing a package whose own new dependency range points
+     * at a version that never actually reached the registry would hand consumers a broken install.
+     * A package's own failure doesn't stop unrelated packages elsewhere in the plan, though.
+     */
+    async function applyPlan(repository, plan, options = {}) {
+        const packageManager = CiService.resolvePackageManager(repository, options.packageManager);
+        const failed = new Set();
+        const result = [];
+        /** The tuple is explicit: `[p.name, p]` widens to `(string | Package)[]`, and whether `new Map`
+         *  still infers `Map<string, Package>` from that came down to which declaration of
+         *  `getPackages()` was in scope - the source one inferred it, the built `.d.ts` did not
+         *  (measured, once the tests started type-checking). */
+        const packagesByName = new Map(repository.getPackages().map(p => [p.name, p]));
+        for (const entry of plan) {
+            if (entry.status !== 'publish') {
+                result.push(entry);
+                continue;
+            }
+            const pkg = entry.package;
+            const blocker = pkg.dependencies.find(d => failed.has(d.name));
+            if (blocker) {
+                failed.add(pkg.name);
+                result.push({ ...entry, status: 'error', reason: `dependency "${blocker.name}" failed to publish` });
+                continue;
+            }
+            const publishDir = resolvePublishDir(pkg, options.contents);
+            const restore = preparePublishManifest(pkg, publishDir, packagesByName);
+            try {
+                /** The plan's own tag, not a recomputed one: `getPlan` decided where this package goes,
+                 *  the reader confirmed that, and `applyPlan` is here to carry it out. `options.tag` is
+                 *  the fallback only for a plan built by something other than `getPlan`. */
+                await exec(buildPublishCommand(packageManager, { ...options, tag: entry.distTag ?? options.tag }), {
+                    cwd: publishDir,
+                    app: pkg.repository.app,
+                    stdio: 'inherit',
+                });
+                result.push(entry);
+            }
+            catch (e) {
+                failed.add(pkg.name);
+                result.push({ ...entry, status: 'error', reason: e.message });
+            }
+            finally {
+                restore?.();
+            }
+        }
+        return result;
+    }
+    PublishService.applyPlan = applyPlan;
+})(PublishService || (PublishService = {}));
+/** Where the publishable output lives, most specific statement first: the package's own
+ *  `publishConfig.directory` (npm/pnpm's native spelling, and a statement about that one package),
+ *  then `.rmanrc "publish.npm.directory"` (which a `"[*]"` block can say once for a whole repository
+ *  instead of repeating in every `package.json`), then `--contents` for a single run. */
+function resolvePublishDir(pkg, contentsOverride) {
+    const native = pkg.manifest.raw.publishConfig?.directory;
+    const configured = pkg.config?.publish?.npm?.directory;
+    const rel = (typeof native === 'string' && native) || configured || contentsOverride;
+    return rel ? path.resolve(pkg.dirname, rel) : pkg.dirname;
+}
+/**
+ * The retired `publish.directory` spelling, if a config still carries it.
+ *
+ * **Caught and refused, never ignored**, and the reason is what ignoring it would do: the key would
+ * silently stop being read, `resolvePublishDir` would fall back to the package's own directory, and
+ * the run would publish the *source tree* to npm instead of the build output. A rename that fails
+ * loudly costs one error message; one that goes quiet ships TypeScript sources to the registry.
+ *
+ * Checked in `getPlan` rather than at the write, for the same reason `version` validates its stamp
+ * list first: a configuration mistake has to surface before anything is published, and an `'error'`
+ * entry aborts the whole plan.
+ *
+ * YAML and JSON configs are unchecked at author time - there is no JSON Schema any more - so this is
+ * the only thing standing between the old spelling and a wrong publish.
+ */
+function retiredDirectoryKey(pkg) {
+    return pkg.config?.publish?.directory !== undefined;
+}
+/**
+ * Which dist-tag a package publishes under, or why the plan must refuse to publish it at all.
+ *
+ * **A prerelease names its own tag, so rman uses it**: `2.0.0-beta.1` goes to `beta`. That is a
+ * reading rather than a guess - the identifier is written in the version - and it is the whole
+ * point, because `npm publish` with no `--tag` writes **`latest`**. A beta that lands there is what
+ * every plain `npm install <name>` resolves to from then on; npm is content to point `latest` at a
+ * prerelease, and `npm dist-tag` can move it back only after everyone who installed in between
+ * already has the beta.
+ *
+ * **It is recorded in the plan rather than applied silently.** The derived tag becomes the entry's
+ * `distTag` and is printed beside the package, so where a version is going is something the reader
+ * confirms. Deriving it and saying nothing would be the same class of mistake in the other
+ * direction - the wrong tag is recoverable (`npm dist-tag add`), but only by someone who noticed.
+ *
+ * Two cases still refuse, because there is no honest answer to derive:
+ *
+ * - **an explicit `--tag latest` on a prerelease.** Someone who typed it is far likelier to have
+ *   confused themselves than to mean it, and the escape hatch for genuinely meaning it - a bare
+ *   `npm publish --tag latest` - is one command away.
+ * - **a prerelease with no identifier to name** (`2.0.0-1`, whose prerelease part is numeric).
+ *   `VersionScheme.prereleaseId` answers `undefined` there rather than inventing a tag called `1`.
+ *
+ * **Both questions are the scheme's, not semver's** - `isPrerelease` and `prereleaseId` - and a
+ * **calendar version has to be ruled out first**: `2026.9.15-1430` carries a semver prerelease
+ * identifier by construction, because that is how the time is spelled, and it says nothing about
+ * the release being a preview. `github-release`'s own `resolvePrerelease` makes the same pair of
+ * checks; they agree deliberately.
+ */
+function distTagFor(pkg, tag) {
+    const isPreview = !isCalendarVersion(pkg.version) && pkg.versionScheme.isPrerelease(pkg.version);
+    if (!isPreview)
+        return { tag };
+    if (tag) {
+        if (tag !== 'latest')
+            return { tag };
+        return {
+            error: `${pkg.version} is a prerelease, so --tag latest would make it what every plain ` +
+                'install resolves to - drop the flag to publish it under its own identifier instead',
+        };
+    }
+    const derived = pkg.versionScheme.prereleaseId(pkg.version);
+    if (derived)
+        return { tag: derived };
+    return {
+        error: `${pkg.version} is a prerelease with no identifier to name a dist-tag after, and with ` +
+            'no --tag npm would put it on "latest" - pass --tag <name>',
+    };
+}
+function buildPublishCommand(packageManager, options) {
+    const args = ['publish'];
+    if (options.access)
+        args.push('--access', options.access);
+    if (options.tag)
+        args.push('--tag', options.tag);
+    if (options.otp)
+        args.push('--otp', options.otp);
+    if (options.registry)
+        args.push('--registry', options.registry);
+    if (options.userconfig)
+        args.push('--userconfig', options.userconfig);
+    return `${packageManager} ${args.join(' ')}`;
+}

package/plugins/node/services/version-plan.service.d.ts

@@ -0,0 +1,44 @@
+import type { Package } from '../../../core/package.js';
+import { VersionPlanService } from '../../../services/version-plan.service.js';
+import type { GitHelper } from '../../../utils/git.js';
+/**
+ * How a release is planned for an npm repository.
+ *
+ * rman's core holds the parts that are true of any repository - groups, conventional-commit
+ * severities, the cascade mechanics, the monorepo root's release identity - and leaves two decisions
+ * abstract because they are statements about an *ecosystem* rather than about releases. This is
+ * npm's pair of answers.
+ *
+ * Registered through the plugin's `versionPlanner`, so `rman version`/`rman changed` work in a
+ * repository that registered the `node` built-in and say what is missing in one that did not.
+ */
+export declare class NodeVersionPlanService extends VersionPlanService {
+    /**
+     * The shared `ChangeHashService.detect`, unmodified: this package's own latest release tag, and failing
+     * that whatever `Plugin.publishedVersion` reports, mapped back onto a tag name.
+     *
+     * **Nothing npm-specific is passed in any more**, and that is the point of the seam moving: the
+     * registry lookup is `packageJsonManifest.publishedVersion`'s now, dispatched per package, so this
+     * override exists only because `detectBoundary` is abstract. If the core ever makes it a concrete
+     * default, this method can go entirely.
+     */
+    protected detectBoundary(git: GitHelper, pkg: Package): Promise<string | undefined>;
+    /**
+     * npm's dependency ranges, read as a release policy. What decides each case is whether a
+     * dependent's **range floor** has to move for a consumer to get a correct install:
+     *
+     * - **patch** - only the changed packages. A dependent's `^1.2.0` already resolves to `1.2.1`,
+     *   and a patch adds nothing for the dependent to require, so nothing downstream has to ship for
+     *   consumers to receive it.
+     * - **minor** - also every transitive in-group dependent. A minor adds API; a dependent that uses
+     *   it is only correct once its own published range requires the new floor, and a range lives in
+     *   a manifest, which only a release puts on the registry.
+     * - **major** - the whole group, changed or not. A breaking change restates every member's
+     *   compatibility, including the members that merely point at one.
+     *
+     * None of this is about versions, which is why it is not in the core: an ecosystem that pins exact
+     * versions instead has to release every dependent for a patch as well, and one that resolves
+     * dependencies from source may not need a release for any of it.
+     */
+    protected cascade(bump: string): VersionPlanService.Cascade;
+}

package/plugins/node/services/version-plan.service.js

@@ -0,0 +1,58 @@
+import { ChangeHashService } from '../../../services/change-hash.service.js';
+import { VersionPlanService } from '../../../services/version-plan.service.js';
+/**
+ * How a release is planned for an npm repository.
+ *
+ * rman's core holds the parts that are true of any repository - groups, conventional-commit
+ * severities, the cascade mechanics, the monorepo root's release identity - and leaves two decisions
+ * abstract because they are statements about an *ecosystem* rather than about releases. This is
+ * npm's pair of answers.
+ *
+ * Registered through the plugin's `versionPlanner`, so `rman version`/`rman changed` work in a
+ * repository that registered the `node` built-in and say what is missing in one that did not.
+ */
+export class NodeVersionPlanService extends VersionPlanService {
+    /**
+     * The shared `ChangeHashService.detect`, unmodified: this package's own latest release tag, and failing
+     * that whatever `Plugin.publishedVersion` reports, mapped back onto a tag name.
+     *
+     * **Nothing npm-specific is passed in any more**, and that is the point of the seam moving: the
+     * registry lookup is `packageJsonManifest.publishedVersion`'s now, dispatched per package, so this
+     * override exists only because `detectBoundary` is abstract. If the core ever makes it a concrete
+     * default, this method can go entirely.
+     */
+    detectBoundary(git, pkg) {
+        return ChangeHashService.detect(git, pkg);
+    }
+    /**
+     * npm's dependency ranges, read as a release policy. What decides each case is whether a
+     * dependent's **range floor** has to move for a consumer to get a correct install:
+     *
+     * - **patch** - only the changed packages. A dependent's `^1.2.0` already resolves to `1.2.1`,
+     *   and a patch adds nothing for the dependent to require, so nothing downstream has to ship for
+     *   consumers to receive it.
+     * - **minor** - also every transitive in-group dependent. A minor adds API; a dependent that uses
+     *   it is only correct once its own published range requires the new floor, and a range lives in
+     *   a manifest, which only a release puts on the registry.
+     * - **major** - the whole group, changed or not. A breaking change restates every member's
+     *   compatibility, including the members that merely point at one.
+     *
+     * None of this is about versions, which is why it is not in the core: an ecosystem that pins exact
+     * versions instead has to release every dependent for a patch as well, and one that resolves
+     * dependencies from source may not need a release for any of it.
+     */
+    cascade(bump) {
+        /** Only semver's three can arrive - `getPlan` validates against `bumpNames` and
+         *  `packageJsonManifest` leaves the scheme at the semver default. The fallback is for a scheme
+         *  someone swaps in underneath this planner, and it over-reaches on purpose: releasing a package
+         *  that did not need it is noise, while under-reaching ships a dependent whose published range
+         *  floor is wrong, which is a broken install. */
+        return CASCADE_BY_BUMP[bump] ?? 'group';
+    }
+}
+/** semver's bump names against how far each has to reach - see `NodeVersionPlanService.cascade`. */
+const CASCADE_BY_BUMP = {
+    patch: 'changed',
+    minor: 'dependents',
+    major: 'group',
+};

package/plugins/node/utils/npm-view.d.ts

@@ -0,0 +1,48 @@
+/** What the registry knows about one package - the two halves `publish` needs, from one call. */
+export interface NpmPackageView {
+    /** The version the **`latest` dist-tag** points at, which is what a bare `npm install <name>`
+     *  resolves to. Not necessarily the highest: a prerelease published under its own tag, or a
+     *  patch to an older line, leaves `latest` where it was. */
+    latest?: string;
+    /** Every version ever published, `latest` included. */
+    versions: string[];
+}
+/**
+ * `npm view <name> version versions --json` - `undefined` for anything that is not an answer (never
+ * published, no network, private or restricted with no access). Catch-everything on purpose: every
+ * caller treats "no answer" as a legitimate state rather than a failure.
+ *
+ * **Two fields in one call, because the two questions are genuinely different and `publish` needs
+ * both.** Whether *this* version is already out there decides `up-to-date` vs `publish`, and only
+ * `versions` can answer it; what `latest` points at is what the plan *reports*, so a reader can see
+ * where the registry stands. Asking `latest` alone was the same approximation in both roles, and it
+ * is wrong in both directions: a prerelease on its own dist-tag never moves `latest`, so `publish`
+ * kept proposing an already-published version until npm answered 403; and a package whose local
+ * version is *behind* `latest` was proposed just as wrongly.
+ *
+ * **`versions` is normalized to an array defensively, and the reason is what happens if it is
+ * not.** `includes` exists on a string too, so a bare `"1.0.0"` would answer `versions.includes()`
+ * without any error at all - and answer it by substring, where `"1.0.10".includes("1.0.1")` is
+ * `true` (measured). npm's own `--json` output *is* a real array here on this npm (measured: a
+ * single-entry `maintainers` comes back as `[...]`, not unwrapped), so this guards a shape
+ * difference across npm versions rather than one I reproduced - but a silent wrong answer about
+ * whether a version is published is worth two lines.
+ */
+export declare function npmViewPackage(name: string, cwd: string, options?: {
+    registry?: string;
+    userconfig?: string;
+}): Promise<NpmPackageView | undefined>;
+/**
+ * `npm view <name> version` - the **`latest` dist-tag's** version, or `undefined` for anything that
+ * is not an answer.
+ *
+ * `packageJsonManifest.publishedVersion` asks this so that `detectChangeHash` can guess a tag name
+ * for a package with no release tag at all, and `latest` is the right question for it: it wants the
+ * one version the ecosystem considers current, not the set of everything ever published. It passes
+ * no options - a bare `npm view` already picks up the repository's own `.npmrc` from `cwd`, which
+ * is what that path wants. `publish` asks `npmViewPackage` instead; see there for why.
+ */
+export declare function npmViewVersion(name: string, cwd: string, options?: {
+    registry?: string;
+    userconfig?: string;
+}): Promise<string | undefined>;

package/plugins/node/utils/npm-view.js

@@ -0,0 +1,71 @@
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+/**
+ * `npm view <name> version versions --json` - `undefined` for anything that is not an answer (never
+ * published, no network, private or restricted with no access). Catch-everything on purpose: every
+ * caller treats "no answer" as a legitimate state rather than a failure.
+ *
+ * **Two fields in one call, because the two questions are genuinely different and `publish` needs
+ * both.** Whether *this* version is already out there decides `up-to-date` vs `publish`, and only
+ * `versions` can answer it; what `latest` points at is what the plan *reports*, so a reader can see
+ * where the registry stands. Asking `latest` alone was the same approximation in both roles, and it
+ * is wrong in both directions: a prerelease on its own dist-tag never moves `latest`, so `publish`
+ * kept proposing an already-published version until npm answered 403; and a package whose local
+ * version is *behind* `latest` was proposed just as wrongly.
+ *
+ * **`versions` is normalized to an array defensively, and the reason is what happens if it is
+ * not.** `includes` exists on a string too, so a bare `"1.0.0"` would answer `versions.includes()`
+ * without any error at all - and answer it by substring, where `"1.0.10".includes("1.0.1")` is
+ * `true` (measured). npm's own `--json` output *is* a real array here on this npm (measured: a
+ * single-entry `maintainers` comes back as `[...]`, not unwrapped), so this guards a shape
+ * difference across npm versions rather than one I reproduced - but a silent wrong answer about
+ * whether a version is published is worth two lines.
+ */
+export async function npmViewPackage(name, cwd, options = {}) {
+    const argv = ['view', name, 'version', 'versions', '--json'];
+    if (options.registry)
+        argv.push('--registry', options.registry);
+    if (options.userconfig)
+        argv.push('--userconfig', options.userconfig);
+    try {
+        const { stdout } = await execFileAsync('npm', argv, { cwd });
+        const text = stdout.trim();
+        if (!text)
+            return undefined;
+        const raw = JSON.parse(text);
+        return { latest: raw.version, versions: toVersionList(raw.versions) };
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * `npm view <name> version` - the **`latest` dist-tag's** version, or `undefined` for anything that
+ * is not an answer.
+ *
+ * `packageJsonManifest.publishedVersion` asks this so that `detectChangeHash` can guess a tag name
+ * for a package with no release tag at all, and `latest` is the right question for it: it wants the
+ * one version the ecosystem considers current, not the set of everything ever published. It passes
+ * no options - a bare `npm view` already picks up the repository's own `.npmrc` from `cwd`, which
+ * is what that path wants. `publish` asks `npmViewPackage` instead; see there for why.
+ */
+export async function npmViewVersion(name, cwd, options = {}) {
+    const argv = ['view', name, 'version'];
+    if (options.registry)
+        argv.push('--registry', options.registry);
+    if (options.userconfig)
+        argv.push('--userconfig', options.userconfig);
+    try {
+        const { stdout } = await execFileAsync('npm', argv, { cwd });
+        return stdout.trim() || undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function toVersionList(versions) {
+    if (Array.isArray(versions))
+        return versions;
+    return versions ? [versions] : [];
+}
+const execFileAsync = promisify(execFile);

package/plugins/node/utils/workspace-range.d.ts

@@ -0,0 +1,26 @@
+/**
+ * The `"workspace:"` dependency protocol - pnpm/yarn's spelling for "this dependency is a sibling in
+ * this repository", which npm's own workspaces understand too.
+ *
+ * **The `node` built-in's, because it is a statement about a `package.json` dependency field.** It sat in
+ * rman's core with a comment admitting it was only there because `publish` needed it from out here -
+ * and now `publish`, the manifest provider and the dependency-range rewrite all live in this
+ * package, so nothing in the core ever looked at it.
+ */
+export interface ParsedWorkspaceRange {
+    /** `'*'`/`'^'`/`'~'` for the bare selector forms; `'explicit'` when the protocol is followed by
+     *  a concrete semver version/range instead (e.g. `"workspace:^1.0.0"`, `"workspace:1.0.0"`). */
+    selector: '*' | '^' | '~' | 'explicit';
+    /** Only set when `selector === 'explicit'` - the literal range following `"workspace:"`. */
+    range?: string;
+}
+/** Parses a dependency range value for the pnpm/yarn `"workspace:"` protocol - `undefined` when
+ *  `value` isn't a workspace range at all (a plain semver range, or not a string). */
+export declare function parseWorkspaceRange(value: unknown): ParsedWorkspaceRange | undefined;
+/**
+ * Resolves a parsed workspace range against `version` (the dependency's actual current version)
+ * into the real range a registry consumer would need - the same substitution pnpm/yarn's own
+ * publish performs: `"*"` pins the exact version (no operator), `"^"`/`"~"` prepend themselves to
+ * it, and an explicit range is used verbatim (it was already a real range, just workspace-prefixed).
+ */
+export declare function resolveWorkspaceRange(parsed: ParsedWorkspaceRange, version: string): string;

package/plugins/node/utils/workspace-range.js

@@ -0,0 +1,28 @@
+/** Parses a dependency range value for the pnpm/yarn `"workspace:"` protocol - `undefined` when
+ *  `value` isn't a workspace range at all (a plain semver range, or not a string). */
+export function parseWorkspaceRange(value) {
+    if (typeof value !== 'string' || !value.startsWith('workspace:'))
+        return undefined;
+    const rest = value.slice('workspace:'.length);
+    if (rest === '*' || rest === '^' || rest === '~')
+        return { selector: rest };
+    return { selector: 'explicit', range: rest };
+}
+/**
+ * Resolves a parsed workspace range against `version` (the dependency's actual current version)
+ * into the real range a registry consumer would need - the same substitution pnpm/yarn's own
+ * publish performs: `"*"` pins the exact version (no operator), `"^"`/`"~"` prepend themselves to
+ * it, and an explicit range is used verbatim (it was already a real range, just workspace-prefixed).
+ */
+export function resolveWorkspaceRange(parsed, version) {
+    switch (parsed.selector) {
+        case '*':
+            return version;
+        case '^':
+            return `^${version}`;
+        case '~':
+            return `~${version}`;
+        case 'explicit':
+            return parsed.range;
+    }
+}