rman-node 1.1.1

package/services/publish.service.js

@@ -0,0 +1,258 @@
+/**
+ * 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, filterPackages, GitHelper } from 'rman';
+import { DEPENDENCY_KEYS } from '../augmentation/manifest.augmentation.js';
+import { npmViewVersion } 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. A package with uncommitted local
+     * changes is `'error'` (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, its currently-published registry version (via `npm view`,
+     * queried concurrently across every remaining package) decides the rest: identical to the local
+     * `package.json` version is `'up-to-date'`; anything else (including never having been
+     * published at all) is `'publish'`.
+     *
+     * 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 viewVersion = deps.npmViewVersion ?? ((name, cwd) => npmViewVersion(name, cwd, options));
+        const entries = new Map();
+        const toCheck = [];
+        for (const pkg of packages) {
+            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 (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 registryVersion = await viewVersion(pkg.name, pkg.dirname);
+            entries.set(pkg.name, {
+                package: pkg,
+                version: pkg.version,
+                registryVersion,
+                status: registryVersion === pkg.version ? 'up-to-date' : 'publish',
+                reason: 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 {
+                await exec(buildPublishCommand(packageManager, options), { cwd: publishDir, 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.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?.directory;
+    const rel = (typeof native === 'string' && native) || configured || contentsOverride;
+    return rel ? path.resolve(pkg.dirname, rel) : pkg.dirname;
+}
+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/services/version-plan.service.d.ts

@@ -0,0 +1,50 @@
+import { type GitHelper, type Package, VersionPlanService } from 'rman';
+/**
+ * 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 names `rman-node` and say what is missing in one that does not.
+ */
+export declare class NodeVersionPlanService extends VersionPlanService {
+    /**
+     * The shared `ChangeHashService.detect`, unmodified: this package's own latest release tag, and failing
+     * that whatever `ManifestProvider.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;
+}
+/** Registers the planner with rman. Called by the plugin entry point, once - and declared in the
+ *  plugin object as well, since a plugin loaded through `plugins` should not need an import side
+ *  effect to work. */
+export declare function augmentVersionPlan(): void;
+/** The instance the plugin registers. One is enough: a planner holds no per-run state, and a test
+ *  wanting a different registry answer registers its own `ManifestProvider` instead - which
+ *  exercises the real path rather than a bypass. */
+export declare const nodeVersionPlanner: NodeVersionPlanService;

package/services/version-plan.service.js

@@ -0,0 +1,67 @@
+import { ChangeHashService, VersionPlanService } from 'rman';
+/**
+ * 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 names `rman-node` and say what is missing in one that does not.
+ */
+export class NodeVersionPlanService extends VersionPlanService {
+    /**
+     * The shared `ChangeHashService.detect`, unmodified: this package's own latest release tag, and failing
+     * that whatever `ManifestProvider.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';
+    }
+}
+/** Registers the planner with rman. Called by the plugin entry point, once - and declared in the
+ *  plugin object as well, since a plugin loaded through `plugins` should not need an import side
+ *  effect to work. */
+export function augmentVersionPlan() {
+    VersionPlanService.setPlanner(nodeVersionPlanner);
+}
+/** The instance the plugin registers. One is enough: a planner holds no per-run state, and a test
+ *  wanting a different registry answer registers its own `ManifestProvider` instead - which
+ *  exercises the real path rather than a bypass. */
+export const nodeVersionPlanner = new NodeVersionPlanService();
+/** 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/utils/npm-run-path.d.ts

@@ -0,0 +1,21 @@
+import { BinPath } from 'rman';
+/**
+ * Where npm puts a repository's locally installed executables: `node_modules/.bin`, at **every**
+ * level from `cwd` up to the filesystem root - which is how npm itself resolves a binary, so a
+ * package's `eslint` is found whether it was installed in that package or hoisted to the workspace
+ * root.
+ *
+ * Adapted from [npm-run-path](https://github.com/sindresorhus/npm-run-path), and it used to sit in
+ * rman's core. It is npm's directory layout from end to end: a Cargo or Go repository has no
+ * `node_modules` to walk, and nothing here would ever fire for it.
+ *
+ * **The running `node`'s own directory goes last**, after the walk, and its position is
+ * load-bearing. It is there so a script calling `node` gets the interpreter rman itself runs on
+ * rather than whatever the shell would pick. It also puts rman's own bin directory ahead of the
+ * inherited PATH, which is a measured trap: a nested `rman` invocation inside a `run` script
+ * resolves to the globally installed one, not to the repository's. Shim it in
+ * `<root>/node_modules/.bin` when that has to be overridden - the walk above reaches there first.
+ */
+export declare const npmBinPaths: BinPath.Provider;
+/** Registers the provider with rman. Called by the plugin entry point, once. */
+export declare function augmentBinPath(): void;

package/utils/npm-run-path.js

@@ -0,0 +1,36 @@
+import path from 'node:path';
+import process from 'node:process';
+import { BinPath } from 'rman';
+/**
+ * Where npm puts a repository's locally installed executables: `node_modules/.bin`, at **every**
+ * level from `cwd` up to the filesystem root - which is how npm itself resolves a binary, so a
+ * package's `eslint` is found whether it was installed in that package or hoisted to the workspace
+ * root.
+ *
+ * Adapted from [npm-run-path](https://github.com/sindresorhus/npm-run-path), and it used to sit in
+ * rman's core. It is npm's directory layout from end to end: a Cargo or Go repository has no
+ * `node_modules` to walk, and nothing here would ever fire for it.
+ *
+ * **The running `node`'s own directory goes last**, after the walk, and its position is
+ * load-bearing. It is there so a script calling `node` gets the interpreter rman itself runs on
+ * rather than whatever the shell would pick. It also puts rman's own bin directory ahead of the
+ * inherited PATH, which is a measured trap: a nested `rman` invocation inside a `run` script
+ * resolves to the globally installed one, not to the repository's. Shim it in
+ * `<root>/node_modules/.bin` when that has to be overridden - the walk above reaches there first.
+ */
+export const npmBinPaths = (cwd) => {
+    const result = [];
+    let previous;
+    let dir = path.resolve(cwd);
+    while (previous !== dir) {
+        result.push(path.join(dir, 'node_modules/.bin'));
+        previous = dir;
+        dir = path.resolve(dir, '..');
+    }
+    result.push(path.resolve(cwd, process.execPath, '..'));
+    return result;
+};
+/** Registers the provider with rman. Called by the plugin entry point, once. */
+export function augmentBinPath() {
+    BinPath.addProvider(npmBinPaths);
+}

package/utils/npm-view.d.ts

@@ -0,0 +1,15 @@
+/**
+ * `npm view <name> version` - `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.
+ *
+ * One copy, two callers with different needs: `publish` asks in order to decide whether this exact
+ * version is already out there, and can be pointed at another registry from the CLI
+ * (`--registry`/`--userconfig`); `packageJsonManifest.publishedVersion` asks so that
+ * `detectChangeHash` can guess a tag name, and passes nothing - a bare `npm view` already picks up
+ * the repository's own `.npmrc` from `cwd`, which is what that path wants.
+ */
+export declare function npmViewVersion(name: string, cwd: string, options?: {
+    registry?: string;
+    userconfig?: string;
+}): Promise<string | undefined>;

package/utils/npm-view.js

@@ -0,0 +1,28 @@
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+/**
+ * `npm view <name> version` - `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.
+ *
+ * One copy, two callers with different needs: `publish` asks in order to decide whether this exact
+ * version is already out there, and can be pointed at another registry from the CLI
+ * (`--registry`/`--userconfig`); `packageJsonManifest.publishedVersion` asks so that
+ * `detectChangeHash` can guess a tag name, and passes nothing - a bare `npm view` already picks up
+ * the repository's own `.npmrc` from `cwd`, which is what that path wants.
+ */
+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;
+    }
+}
+const execFileAsync = promisify(execFile);

package/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.
+ *
+ * **In `rman-node`, 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/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;
+    }
+}