@exadev/semantic-release-workspace 1.2.4 → 1.3.0

package/dist/cli.js

@@ -1,20 +1,21 @@
 #!/usr/bin/env node
 import { createRequire } from "node:module";
+import { readFile, writeFile } from "node:fs/promises";
 import { cosmiconfigSync } from "cosmiconfig";
 import { Command, InvalidArgumentError } from "commander";
 import { dirname, relative, resolve, sep } from "node:path";
-import { analyzeCommits } from "@semantic-release/commit-analyzer";
-import { generateNotes } from "@semantic-release/release-notes-generator";
+import { detachRelease, resumeRelease } from "@exadev/release-gate";
 import { execFile } from "node:child_process";
 import { promisify } from "node:util";
-import semanticRelease from "semantic-release";
-import { readFile, writeFile } from "node:fs/promises";
 import validateNpmPackageName from "validate-npm-package-name";
 import { glob } from "tinyglobby";
 import { parse } from "yaml";
+import { analyzeCommits } from "@semantic-release/commit-analyzer";
+import { generateNotes } from "@semantic-release/release-notes-generator";
+import semanticRelease from "semantic-release";
 import { pathToFileURL } from "node:url";
 //#region package.json
-var version = "1.2.4";
+var version = "1.3.0";
 //#endregion
 //#region src/errors.ts
 /**
@@ -60,77 +61,6 @@ var PnpmCommandError = class extends WorkspaceReleaseError {
 	}
 };
 //#endregion
-//#region src/json.ts
-function isJsonObject(value) {
-	return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-function isStringRecord(value) {
-	return isJsonObject(value) && Object.values(value).every((entry) => typeof entry === "string");
-}
-function isStringArray(value) {
-	return Array.isArray(value) && value.every((entry) => typeof entry === "string");
-}
-/**
-* Narrows `unknown` to `unknown[]`. `Array.isArray` alone narrows to `any[]`, whose elements flow as `any` into any later destructuring; going through this guard keeps the elements `unknown` so they must still be narrowed by hand.
-*/
-function isUnknownArray(value) {
-	return Array.isArray(value);
-}
-/**
-* The indentation of the first indented line in a JSON document, so a rewritten manifest keeps the formatting the repository already uses instead of being reflowed to whatever `JSON.stringify` defaults to. A file with no indented line at all (`{}` on one line) has no evidence either way, in which case two spaces -- npm's own default when it writes a `package.json` -- is the closest thing to a neutral choice.
-*/
-const FIRST_INDENTED_LINE = /^[ \t]+(?=")/m;
-const NPM_DEFAULT_INDENT = "  ";
-function detectIndent(text) {
-	const match = FIRST_INDENTED_LINE.exec(text);
-	return match === null ? NPM_DEFAULT_INDENT : match[0];
-}
-/** Serialises a JSON document back to text with the indentation and trailing-newline convention of the text it was read from, so rewriting one dependency range produces a one-line diff rather than a whole-file reformat. */
-function stringifyJsonLike(value, originalText) {
-	const serialised = JSON.stringify(value, null, detectIndent(originalText));
-	return originalText.endsWith("\n") ? `${serialised}\n` : serialised;
-}
-//#endregion
-//#region src/package-name.ts
-const packageName = "@exadev/semantic-release-workspace";
-//#endregion
-//#region src/dependency-bump-commit.ts
-/**
-* The commit message format for a cross-package dependency-range bump, shared between the code that writes it (`bumpDependents` in `release.ts`) and the code that reads it back (`createScopedPlugins` in `plugins.ts`).
-*
-* The subject line alone (`chore(deps): bump @scope/a to ^1.1.0 in @scope/b [skip ci]`) is for humans reading `git log`. Recovering the forced-patch decision from a commit already sitting in history -- rather than only from the in-memory record a single run builds as it goes -- needs a machine-parseable form as well, because a run that starts after a previous run already committed and pushed the bump (whether that previous run crashed immediately afterwards, or simply finished days ago) has no in-memory record at all: the only place the fact "this dependency range changed because a sibling released" is stated is the repository itself. The trailer below is that statement.
-*/
-const TRAILER_DEPENDENCY = "Bumped-Workspace-Dependency";
-const TRAILER_VERSION = "Bumped-Workspace-Dependency-Version";
-const TRAILER_RANGE = "Bumped-Workspace-Dependency-Range";
-/** Builds the full commit message (subject and trailer) for one dependency-range bump. */
-function formatDependencyBumpMessage(info) {
-	return `${`chore(deps): bump ${info.dependency} to ${info.range} in ${info.dependent} [skip ci]`}\n\n${[
-		`${TRAILER_DEPENDENCY}: ${info.dependency}`,
-		`${TRAILER_VERSION}: ${info.version}`,
-		`${TRAILER_RANGE}: ${info.range}`
-	].join("\n")}`;
-}
-/**
-* Recovers the dependency bump a `formatDependencyBumpMessage` commit recorded, from its full git message (subject and body), or `undefined` if the message carries no such trailer. All three lines must be present for the commit to be treated as a bump commit at all -- a message missing even one is left alone rather than partially trusted.
-*/
-function parseDependencyBumpTrailer(message) {
-	const dependency = matchTrailerLine(message, TRAILER_DEPENDENCY);
-	const version = matchTrailerLine(message, TRAILER_VERSION);
-	const range = matchTrailerLine(message, TRAILER_RANGE);
-	if (dependency === void 0 || version === void 0 || range === void 0) return;
-	return {
-		dependency,
-		version,
-		range
-	};
-}
-function matchTrailerLine(message, key) {
-	const prefix = `${key}: `;
-	const line = message.split("\n").find((candidate) => candidate.startsWith(prefix));
-	return line === void 0 ? void 0 : line.slice(prefix.length).trim();
-}
-//#endregion
 //#region src/git.ts
 const execFileAsync$1 = promisify(execFile);
 /** `git log --name-only` over everything since a package's last release tag can legitimately produce tens of megabytes of path output on a long-lived monorepo, well past execFile's default buffer, failing on exactly the big workspaces this tool exists for. */
@@ -315,142 +245,35 @@ function toGitCommandError(args, cwd, cause) {
 	return new GitCommandError(args, cwd, exitCode, stderr !== "" ? stderr : cause instanceof Error ? cause.message : String(cause));
 }
 //#endregion
-//#region src/plugins.ts
-/** The standard publish pipeline this orchestrator coordinates when a workspace configures none of its own. Every entry reuses the corresponding official plugin -- the orchestrator scopes and sequences them per package, it does not reimplement npm publishing, GitHub release creation, or changelog writing. */
-const DEFAULT_PUBLISH_PLUGINS = [
-	"@semantic-release/changelog",
-	"@semantic-release/npm",
-	"@semantic-release/github",
-	["@semantic-release/git", {
-		assets: ["CHANGELOG.md", "package.json"],
-		message: "chore(release): ${nextRelease.gitTag} [skip ci]"
-	}]
-];
-/** The standard publish pipeline for `commitStrategy: 'single'`: the same as `DEFAULT_PUBLISH_PLUGINS` minus @semantic-release/git, which that mode never runs -- see `resolvePublishPlugins`'s `forbidGitPlugin` option for why it is rejected outright rather than merely unused. Single-commit mode does its own committing (one combined commit for every released package), so a `prepare`-step git plugin here would create the very per-package commits that mode exists to avoid. */
-const SINGLE_COMMIT_DEFAULT_PUBLISH_PLUGINS = [
-	"@semantic-release/changelog",
-	"@semantic-release/npm",
-	"@semantic-release/github"
-];
-const STEP_PLUGINS_THE_ORCHESTRATOR_OWNS = /* @__PURE__ */ new Set(["@semantic-release/commit-analyzer", "@semantic-release/release-notes-generator"]);
-/**
-* Builds the per-package `analyzeCommits` and `generateNotes` functions handed to semantic-release as inline plugins.
-*
-* Both apply the same path scoping before delegating to the real @semantic-release/commit-analyzer and @semantic-release/release-notes-generator: the commit list semantic-release already fetched for the release range is filtered down to commits whose `git log --name-only` file list intersects the package's own directory, and only the filtered list reaches the standard plugin. Conventional-commit parsing and changelog formatting stay entirely inside the standard plugins.
-*
-* The `analyzeCommits` wrapper carries one addition beyond filtering: when the standard analyzer finds no releasable commits but a workspace dependency range of the package's has changed, it returns 'patch' anyway. A dependent whose only change is a dependency bump still needs a release for that range to reach the registry. "Has changed" is read from two sources, merged: bumps recorded in memory earlier in the current run (`scope.bumps`), and bumps recorded in the package's own filtered commit history via the trailer `dependency-bump-commit.ts` writes and reads -- the latter is what lets a run that starts after a previous run already committed and pushed the bump (a crash recovery, or simply a later run) reach the same decision, rather than depending on state that existed only inside the process that made the commit.
-*/
-function createScopedPlugins(scope) {
-	let cached;
-	async function commitsForPackage(context) {
-		const from = context.lastRelease?.gitHead ?? void 0;
-		if (cached === void 0) cached = {
-			from,
-			paths: changedPathsSince(from, { cwd: context.cwd })
-		};
-		else if (cached.from !== from) cached = {
-			from,
-			paths: changedPathsSince(from, { cwd: context.cwd })
-		};
-		const commits = filterCommitsToDirectory(context.commits, await cached.paths, scope.pkg.repoRelativeDirectory);
-		scope.onCommitsResolved?.(commits);
-		return commits;
-	}
-	return {
-		async analyzeCommits(_pluginConfig, context) {
-			const commits = await commitsForPackage(context);
-			const type = await analyzeCommits(scope.analyzeCommitsConfig, {
-				...context,
-				commits
-			});
-			if (type) return type;
-			const bumps = mergeDependencyBumps(scope.bumps.bumpsFor(scope.pkg.name), commits);
-			if (bumps.length === 0) return false;
-			context.logger.log(`No releasable commits under ${scope.pkg.relativeDirectory}, but ${bumps.length === 1 ? "a workspace dependency range changed" : `${bumps.length} workspace dependency ranges changed`}; forcing a patch release.`);
-			return "patch";
-		},
-		async generateNotes(_pluginConfig, context) {
-			const commits = await commitsForPackage(context);
-			const notes = await generateNotes(scope.generateNotesConfig, {
-				...context,
-				commits
-			});
-			const bumps = mergeDependencyBumps(scope.bumps.bumpsFor(scope.pkg.name), commits);
-			if (bumps.length === 0) return notes;
-			const section = [
-				"### Dependencies",
-				"",
-				...bumps.map((bump) => describeDependencyBump(bump))
-			].join("\n");
-			return notes ? `${notes}\n\n${section}` : section;
-		}
-	};
+//#region src/json.ts
+function isJsonObject(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
 }
-/**
-* Combines the bumps recorded in memory earlier in the current run with bumps recovered from the package's own filtered commit history (a bump commit from this run, already visible because it touches the package's own directory, or one left over from a previous run), de-duplicated by dependency name. The in-memory entry wins on overlap: it carries the manifest field and dependent name a `resolved-at-publish` bump has no commit to recover from at all.
-*/
-function mergeDependencyBumps(runtimeBumps, commits) {
-	const byDependency = /* @__PURE__ */ new Map();
-	for (const commit of commits) {
-		const parsed = parseDependencyBumpTrailer(commit.message);
-		if (parsed !== void 0) byDependency.set(parsed.dependency, {
-			...parsed,
-			kind: "rewritten"
-		});
-	}
-	for (const bump of runtimeBumps) byDependency.set(bump.dependency, bump);
-	return [...byDependency.values()];
+function isStringRecord(value) {
+	return isJsonObject(value) && Object.values(value).every((entry) => typeof entry === "string");
 }
-function describeDependencyBump(bump) {
-	return bump.kind === "rewritten" ? `- Updated ${bump.dependency} to ${bump.range}` : `- Updated ${bump.dependency} to ${bump.version} (declared as \`${bump.range}\`, resolved by pnpm at publish time)`;
+function isStringArray(value) {
+	return Array.isArray(value) && value.every((entry) => typeof entry === "string");
 }
 /**
-* Keeps a commit for the package when any path it changed lies under the package's directory. The trailing-slash prefix comparison stops `packages/a` from matching `packages/abc/x`.
-*
-* A commit missing from the changed-paths map is kept rather than dropped: it is inside the package's release range (semantic-release put it there), so a failure to parse its file list must not silently swallow a release. Absent evidence errs towards publishing, which is the visible direction for a release tool.
+* Narrows `unknown` to `unknown[]`. `Array.isArray` alone narrows to `any[]`, whose elements flow as `any` into any later destructuring; going through this guard keeps the elements `unknown` so they must still be narrowed by hand.
 */
-function filterCommitsToDirectory(commits, changedPaths, directory) {
-	const prefix = `${directory}/`;
-	return commits.filter((commit) => {
-		const paths = changedPaths.get(commit.hash);
-		if (paths === void 0) return true;
-		return [...paths].some((path) => path === directory || path.startsWith(prefix));
-	});
-}
-function resolvePublishPlugins(specs, workspaceRoot, options) {
-	const requireFromTool = createRequire(import.meta.url);
-	const requireFromWorkspace = createRequire(resolve(workspaceRoot, "package.json"));
-	const resolved = [];
-	let hasGitPlugin = false;
-	for (const spec of specs) {
-		const [name, config] = parsePublishPluginSpec(spec);
-		if (STEP_PLUGINS_THE_ORCHESTRATOR_OWNS.has(name)) throw new ReleaseConfigurationError(`"${name}" is listed as a publish plugin, but ${packageName} always provides the ${name === "@semantic-release/commit-analyzer" ? "analyzeCommits" : "generateNotes"} step itself, wrapped around that plugin. Passing it here would make its configuration a silent no-op; set that configuration on the orchestrator's analyzeCommits/generateNotes options instead.`);
-		if (name === "@semantic-release/git") {
-			hasGitPlugin = true;
-			if (options.forbidGitPlugin === true) throw new ReleaseConfigurationError(`"@semantic-release/git" is listed as a publish plugin, but commitStrategy "single" does its own committing -- one combined commit for every released package, tagged once every package has been analysed -- rather than letting each package's own release commit itself. Remove @semantic-release/git from the plugin list; its version bump and changelog write still happen (via its sibling prepare plugins), just folded into the combined commit instead of made on their own.`);
-		}
-		const entry = [resolvePluginModule(name, requireFromTool, requireFromWorkspace), config];
-		resolved.push(entry);
-	}
-	if (options.requireGitPlugin && !hasGitPlugin) throw new ReleaseConfigurationError(`The publish plugin list does not include @semantic-release/git. Without it, nothing commits each released package's manifest and changelog back to the branch, so the repository would drift out of agreement with the published versions -- the exact divergence this tool exists to prevent. (Dry runs are exempt.)`);
-	return resolved;
+function isUnknownArray(value) {
+	return Array.isArray(value);
 }
 /**
-* Resolves a plugin module name to an absolute file path, first from this tool's own module context (its peer dependencies, which every workspace installing the orchestrator must provide) and then from the workspace root (a workspace's own plugin dependencies, such as a custom changelog plugin). Both bases are named in the error when neither can resolve the name.
+* The indentation of the first indented line in a JSON document, so a rewritten manifest keeps the formatting the repository already uses instead of being reflowed to whatever `JSON.stringify` defaults to. A file with no indented line at all (`{}` on one line) has no evidence either way, in which case two spaces -- npm's own default when it writes a `package.json` -- is the closest thing to a neutral choice.
 */
-function resolvePluginModule(name, requireFromTool, requireFromWorkspace) {
-	const attempts = [];
-	for (const [label, requirer] of [["this tool", requireFromTool], ["the workspace root", requireFromWorkspace]]) try {
-		return requirer.resolve(name);
-	} catch (cause) {
-		attempts.push(`${label}: ${cause instanceof Error ? cause.message : String(cause)}`);
-	}
-	throw new ReleaseConfigurationError(`Cannot resolve the publish plugin "${name}". Tried resolving it from ${attempts.join("; and from ")}.`);
+const FIRST_INDENTED_LINE = /^[ \t]+(?=")/m;
+const NPM_DEFAULT_INDENT = "  ";
+function detectIndent(text) {
+	const match = FIRST_INDENTED_LINE.exec(text);
+	return match === null ? NPM_DEFAULT_INDENT : match[0];
 }
-function parsePublishPluginSpec(spec) {
-	if (typeof spec === "string") return [spec, {}];
-	const [name, config] = spec;
-	return [name, config ?? {}];
+/** Serialises a JSON document back to text with the indentation and trailing-newline convention of the text it was read from, so rewriting one dependency range produces a one-line diff rather than a whole-file reformat. */
+function stringifyJsonLike(value, originalText) {
+	const serialised = JSON.stringify(value, null, detectIndent(originalText));
+	return originalText.endsWith("\n") ? `${serialised}\n` : serialised;
 }
 //#endregion
 //#region src/manifest.ts
@@ -732,6 +555,184 @@ function mustGet(map, key, what) {
 	return value;
 }
 //#endregion
+//#region src/package-name.ts
+const packageName = "@exadev/semantic-release-workspace";
+//#endregion
+//#region src/dependency-bump-commit.ts
+/**
+* The commit message format for a cross-package dependency-range bump, shared between the code that writes it (`bumpDependents` in `release.ts`) and the code that reads it back (`createScopedPlugins` in `plugins.ts`).
+*
+* The subject line alone (`chore(deps): bump @scope/a to ^1.1.0 in @scope/b [skip ci]`) is for humans reading `git log`. Recovering the forced-patch decision from a commit already sitting in history -- rather than only from the in-memory record a single run builds as it goes -- needs a machine-parseable form as well, because a run that starts after a previous run already committed and pushed the bump (whether that previous run crashed immediately afterwards, or simply finished days ago) has no in-memory record at all: the only place the fact "this dependency range changed because a sibling released" is stated is the repository itself. The trailer below is that statement.
+*/
+const TRAILER_DEPENDENCY = "Bumped-Workspace-Dependency";
+const TRAILER_VERSION = "Bumped-Workspace-Dependency-Version";
+const TRAILER_RANGE = "Bumped-Workspace-Dependency-Range";
+/** Builds the full commit message (subject and trailer) for one dependency-range bump. */
+function formatDependencyBumpMessage(info) {
+	return `${`chore(deps): bump ${info.dependency} to ${info.range} in ${info.dependent} [skip ci]`}\n\n${[
+		`${TRAILER_DEPENDENCY}: ${info.dependency}`,
+		`${TRAILER_VERSION}: ${info.version}`,
+		`${TRAILER_RANGE}: ${info.range}`
+	].join("\n")}`;
+}
+/**
+* Recovers the dependency bump a `formatDependencyBumpMessage` commit recorded, from its full git message (subject and body), or `undefined` if the message carries no such trailer. All three lines must be present for the commit to be treated as a bump commit at all -- a message missing even one is left alone rather than partially trusted.
+*/
+function parseDependencyBumpTrailer(message) {
+	const dependency = matchTrailerLine(message, TRAILER_DEPENDENCY);
+	const version = matchTrailerLine(message, TRAILER_VERSION);
+	const range = matchTrailerLine(message, TRAILER_RANGE);
+	if (dependency === void 0 || version === void 0 || range === void 0) return;
+	return {
+		dependency,
+		version,
+		range
+	};
+}
+function matchTrailerLine(message, key) {
+	const prefix = `${key}: `;
+	const line = message.split("\n").find((candidate) => candidate.startsWith(prefix));
+	return line === void 0 ? void 0 : line.slice(prefix.length).trim();
+}
+//#endregion
+//#region src/plugins.ts
+/** The standard publish pipeline this orchestrator coordinates when a workspace configures none of its own. Every entry reuses the corresponding official plugin -- the orchestrator scopes and sequences them per package, it does not reimplement npm publishing, GitHub release creation, or changelog writing. */
+const DEFAULT_PUBLISH_PLUGINS = [
+	"@semantic-release/changelog",
+	"@semantic-release/npm",
+	"@semantic-release/github",
+	["@semantic-release/git", {
+		assets: ["CHANGELOG.md", "package.json"],
+		message: "chore(release): ${nextRelease.gitTag} [skip ci]"
+	}]
+];
+/** The standard publish pipeline for `commitStrategy: 'single'`: the same as `DEFAULT_PUBLISH_PLUGINS` minus @semantic-release/git, which that mode never runs -- see `resolvePublishPlugins`'s `forbidGitPlugin` option for why it is rejected outright rather than merely unused. Single-commit mode does its own committing (one combined commit for every released package), so a `prepare`-step git plugin here would create the very per-package commits that mode exists to avoid. */
+const SINGLE_COMMIT_DEFAULT_PUBLISH_PLUGINS = [
+	"@semantic-release/changelog",
+	"@semantic-release/npm",
+	"@semantic-release/github"
+];
+const STEP_PLUGINS_THE_ORCHESTRATOR_OWNS = /* @__PURE__ */ new Set(["@semantic-release/commit-analyzer", "@semantic-release/release-notes-generator"]);
+/**
+* Builds the per-package `analyzeCommits` and `generateNotes` functions handed to semantic-release as inline plugins.
+*
+* Both apply the same path scoping before delegating to the real @semantic-release/commit-analyzer and @semantic-release/release-notes-generator: the commit list semantic-release already fetched for the release range is filtered down to commits whose `git log --name-only` file list intersects the package's own directory, and only the filtered list reaches the standard plugin. Conventional-commit parsing and changelog formatting stay entirely inside the standard plugins.
+*
+* The `analyzeCommits` wrapper carries one addition beyond filtering: when the standard analyzer finds no releasable commits but a workspace dependency range of the package's has changed, it returns 'patch' anyway. A dependent whose only change is a dependency bump still needs a release for that range to reach the registry. "Has changed" is read from two sources, merged: bumps recorded in memory earlier in the current run (`scope.bumps`), and bumps recorded in the package's own filtered commit history via the trailer `dependency-bump-commit.ts` writes and reads -- the latter is what lets a run that starts after a previous run already committed and pushed the bump (a crash recovery, or simply a later run) reach the same decision, rather than depending on state that existed only inside the process that made the commit.
+*/
+function createScopedPlugins(scope) {
+	let cached;
+	async function commitsForPackage(context) {
+		const from = context.lastRelease?.gitHead ?? void 0;
+		if (cached === void 0) cached = {
+			from,
+			paths: changedPathsSince(from, { cwd: context.cwd })
+		};
+		else if (cached.from !== from) cached = {
+			from,
+			paths: changedPathsSince(from, { cwd: context.cwd })
+		};
+		const commits = filterCommitsToDirectory(context.commits, await cached.paths, scope.pkg.repoRelativeDirectory);
+		scope.onCommitsResolved?.(commits);
+		return commits;
+	}
+	return {
+		async analyzeCommits(_pluginConfig, context) {
+			const commits = await commitsForPackage(context);
+			const type = await analyzeCommits(scope.analyzeCommitsConfig, {
+				...context,
+				commits
+			});
+			if (type) return type;
+			const bumps = mergeDependencyBumps(scope.bumps.bumpsFor(scope.pkg.name), commits);
+			if (bumps.length === 0) return false;
+			context.logger.log(`No releasable commits under ${scope.pkg.relativeDirectory}, but ${bumps.length === 1 ? "a workspace dependency range changed" : `${bumps.length} workspace dependency ranges changed`}; forcing a patch release.`);
+			return "patch";
+		},
+		async generateNotes(_pluginConfig, context) {
+			const commits = await commitsForPackage(context);
+			const notes = await generateNotes(scope.generateNotesConfig, {
+				...context,
+				commits
+			});
+			const bumps = mergeDependencyBumps(scope.bumps.bumpsFor(scope.pkg.name), commits);
+			if (bumps.length === 0) return notes;
+			const section = [
+				"### Dependencies",
+				"",
+				...bumps.map((bump) => describeDependencyBump(bump))
+			].join("\n");
+			return notes ? `${notes}\n\n${section}` : section;
+		}
+	};
+}
+/**
+* Combines the bumps recorded in memory earlier in the current run with bumps recovered from the package's own filtered commit history (a bump commit from this run, already visible because it touches the package's own directory, or one left over from a previous run), de-duplicated by dependency name. The in-memory entry wins on overlap: it carries the manifest field and dependent name a `resolved-at-publish` bump has no commit to recover from at all.
+*/
+function mergeDependencyBumps(runtimeBumps, commits) {
+	const byDependency = /* @__PURE__ */ new Map();
+	for (const commit of commits) {
+		const parsed = parseDependencyBumpTrailer(commit.message);
+		if (parsed !== void 0) byDependency.set(parsed.dependency, {
+			...parsed,
+			kind: "rewritten"
+		});
+	}
+	for (const bump of runtimeBumps) byDependency.set(bump.dependency, bump);
+	return [...byDependency.values()];
+}
+function describeDependencyBump(bump) {
+	return bump.kind === "rewritten" ? `- Updated ${bump.dependency} to ${bump.range}` : `- Updated ${bump.dependency} to ${bump.version} (declared as \`${bump.range}\`, resolved by pnpm at publish time)`;
+}
+/**
+* Keeps a commit for the package when any path it changed lies under the package's directory. The trailing-slash prefix comparison stops `packages/a` from matching `packages/abc/x`.
+*
+* A commit missing from the changed-paths map is kept rather than dropped: it is inside the package's release range (semantic-release put it there), so a failure to parse its file list must not silently swallow a release. Absent evidence errs towards publishing, which is the visible direction for a release tool.
+*/
+function filterCommitsToDirectory(commits, changedPaths, directory) {
+	const prefix = `${directory}/`;
+	return commits.filter((commit) => {
+		const paths = changedPaths.get(commit.hash);
+		if (paths === void 0) return true;
+		return [...paths].some((path) => path === directory || path.startsWith(prefix));
+	});
+}
+function resolvePublishPlugins(specs, workspaceRoot, options) {
+	const requireFromTool = createRequire(import.meta.url);
+	const requireFromWorkspace = createRequire(resolve(workspaceRoot, "package.json"));
+	const resolved = [];
+	let hasGitPlugin = false;
+	for (const spec of specs) {
+		const [name, config] = parsePublishPluginSpec(spec);
+		if (STEP_PLUGINS_THE_ORCHESTRATOR_OWNS.has(name)) throw new ReleaseConfigurationError(`"${name}" is listed as a publish plugin, but ${packageName} always provides the ${name === "@semantic-release/commit-analyzer" ? "analyzeCommits" : "generateNotes"} step itself, wrapped around that plugin. Passing it here would make its configuration a silent no-op; set that configuration on the orchestrator's analyzeCommits/generateNotes options instead.`);
+		if (name === "@semantic-release/git") {
+			hasGitPlugin = true;
+			if (options.forbidGitPlugin === true) throw new ReleaseConfigurationError(`"@semantic-release/git" is listed as a publish plugin, but commitStrategy "single" does its own committing -- one combined commit for every released package, tagged once every package has been analysed -- rather than letting each package's own release commit itself. Remove @semantic-release/git from the plugin list; its version bump and changelog write still happen (via its sibling prepare plugins), just folded into the combined commit instead of made on their own.`);
+		}
+		const entry = [resolvePluginModule(name, requireFromTool, requireFromWorkspace), config];
+		resolved.push(entry);
+	}
+	if (options.requireGitPlugin && !hasGitPlugin) throw new ReleaseConfigurationError(`The publish plugin list does not include @semantic-release/git. Without it, nothing commits each released package's manifest and changelog back to the branch, so the repository would drift out of agreement with the published versions -- the exact divergence this tool exists to prevent. (Dry runs are exempt.)`);
+	return resolved;
+}
+/**
+* Resolves a plugin module name to an absolute file path, first from this tool's own module context (its peer dependencies, which every workspace installing the orchestrator must provide) and then from the workspace root (a workspace's own plugin dependencies, such as a custom changelog plugin). Both bases are named in the error when neither can resolve the name.
+*/
+function resolvePluginModule(name, requireFromTool, requireFromWorkspace) {
+	const attempts = [];
+	for (const [label, requirer] of [["this tool", requireFromTool], ["the workspace root", requireFromWorkspace]]) try {
+		return requirer.resolve(name);
+	} catch (cause) {
+		attempts.push(`${label}: ${cause instanceof Error ? cause.message : String(cause)}`);
+	}
+	throw new ReleaseConfigurationError(`Cannot resolve the publish plugin "${name}". Tried resolving it from ${attempts.join("; and from ")}.`);
+}
+function parsePublishPluginSpec(spec) {
+	if (typeof spec === "string") return [spec, {}];
+	const [name, config] = spec;
+	return [name, config ?? {}];
+}
+//#endregion
 //#region src/pnpm.ts
 const execFileAsync = promisify(execFile);
 /**
@@ -1025,6 +1026,10 @@ async function loadReleasePlugin(absolutePath, cache) {
 * For each package, in topological order: run semantic-release's programmatic API with `cwd` scoped to the package directory, a `name@version` tag format to keep each package's tags distinct in the one shared tag namespace, and inline `analyzeCommits`/`generateNotes` plugins that filter the release range's commits down to the package's own directory before delegating to the standard plugins. When a package releases, every workspace package that depends on it and has not run yet gets its dependency range rewritten in its manifest and committed immediately -- before its own turn, so its commit analysis and its published manifest both see the new range.
 */
 async function releaseWorkspace(options = {}) {
+	if (options.gatePublish === true) {
+		if ((options.commitStrategy ?? "per-package") === "single") throw new ReleaseConfigurationError("gatePublish is not supported together with commitStrategy: \"single\" -- single-commit-release.ts's tag/publish machinery is entirely bespoke and never goes through semantic-release's own run(), so it has no insertion point for release-gate's detach/resume primitives.");
+		return detachWorkspaceRelease(options);
+	}
 	if ((options.commitStrategy ?? "per-package") === "single") return releaseWorkspaceSingleCommit(options);
 	const root = resolve(options.root ?? process.cwd());
 	const log = options.log ?? console.log;
@@ -1038,40 +1043,65 @@ async function releaseWorkspace(options = {}) {
 	const publishPlugins = resolvePublishPlugins(options.plugins ?? DEFAULT_PUBLISH_PLUGINS, workspace.root, { requireGitPlugin: !dryRun });
 	const analyzeCommitsConfig = options.analyzeCommits ?? {};
 	const generateNotesConfig = options.generateNotes ?? {};
+	return {
+		order,
+		packages: (await runReleaseLoop(graph, order, workspace, dryRun, log, async (pkg, bumpsForThisPackage) => {
+			const result = await runPackageRelease(pkg, {
+				publishPlugins,
+				analyzeCommitsConfig,
+				generateNotesConfig,
+				bumpsForThisPackage,
+				dryRun,
+				env,
+				branches: options.branches
+			});
+			const nextRelease = result === false ? void 0 : result.nextRelease;
+			return {
+				released: nextRelease !== void 0,
+				version: nextRelease?.version,
+				result
+			};
+		})).map((entry) => {
+			const nextRelease = entry.result === false ? void 0 : entry.result.nextRelease;
+			return {
+				name: entry.name,
+				directory: entry.directory,
+				released: nextRelease !== void 0,
+				version: nextRelease?.version,
+				gitTag: nextRelease?.gitTag,
+				type: nextRelease?.type,
+				dependencyBumps: entry.dependencyBumps
+			};
+		})
+	};
+}
+/**
+* The per-package release loop shared by `releaseWorkspace` (normal per-package releases) and `detachWorkspaceRelease` (gated tag-only releases): iterate the topological `order`, call the caller's own `releaseOne` for each package, record which dependency-range bumps were already applied to it, and -- when it released -- bump every workspace dependent's manifest before that dependent's own turn (see `bumpDependents`'s doc comment for why this happens immediately rather than being staged). The two call sites differ only in how they call semantic-release (`semanticRelease(...)` vs `detachRelease(...)`) and how they read "did it release, and what version" off the result, both captured by `releaseOne`.
+*/
+async function runReleaseLoop(graph, order, workspace, dryRun, log, releaseOne) {
 	const pendingBumps = /* @__PURE__ */ new Map();
 	let identity;
-	const outcomes = [];
+	const entries = [];
 	for (const name of order) {
 		const pkg = mustGet(graph.packages, name, "package");
 		const bumpsForThisPackage = pendingBumps.get(name) ?? [];
 		log(`Releasing ${name} from ${pkg.relativeDirectory}${bumpsForThisPackage.length > 0 ? ` (dependency ranges already bumped: ${bumpsForThisPackage.map((bump) => bump.dependency).join(", ")})` : ""}`);
-		const result = await runPackageRelease(pkg, {
-			publishPlugins,
-			analyzeCommitsConfig,
-			generateNotesConfig,
-			bumpsForThisPackage,
-			dryRun,
-			env,
-			branches: options.branches
-		});
-		const nextRelease = result === false ? void 0 : result.nextRelease;
-		outcomes.push({
+		const { released, version, result } = await releaseOne(pkg, bumpsForThisPackage);
+		entries.push({
 			name,
 			directory: pkg.directory,
-			released: nextRelease !== void 0,
-			version: nextRelease?.version,
-			gitTag: nextRelease?.gitTag,
-			type: nextRelease?.type,
+			relativeDirectory: pkg.relativeDirectory,
+			result,
 			dependencyBumps: bumpsForThisPackage
 		});
 		pendingBumps.delete(name);
-		if (nextRelease === void 0) {
+		if (!released || version === void 0) {
 			log(`${name}: no release`);
 			continue;
 		}
-		log(`${name}: released ${nextRelease.gitTag}`);
+		log(`${name}: released ${version}`);
 		identity ??= await resolveCommitIdentity({ cwd: workspace.root });
-		const bumps = await bumpDependents(pkg, nextRelease.version, graph, {
+		const bumps = await bumpDependents(pkg, version, graph, {
 			workspace,
 			dryRun,
 			identity,
@@ -1083,10 +1113,7 @@ async function releaseWorkspace(options = {}) {
 			pendingBumps.set(bump.dependent, forDependent);
 		}
 	}
-	return {
-		order,
-		packages: outcomes
-	};
+	return entries;
 }
 async function runPackageRelease(pkg, options) {
 	const scoped = createScopedPlugins({
@@ -1157,6 +1184,146 @@ async function bumpDependents(released, version, graph, options) {
 	return applied;
 }
 //#endregion
+//#region src/gate-publish.ts
+/**
+* The `gatePublish: true` half of `releaseWorkspace`: tags and pushes every due package via `@exadev/release-gate`'s `detachRelease`, but never publishes. Built on the same `runReleaseLoop` the normal per-package path uses, so dependency-range bumps between packages happen identically either way -- only the release call itself (`detachRelease` instead of `semanticRelease`) and how "did it release" gets read differ.
+*/
+async function detachWorkspaceRelease(options) {
+	const root = resolve(options.root ?? process.cwd());
+	const log = options.log ?? console.log;
+	const dryRun = options.dryRun === true;
+	const env = sanitizeGitEnv(options.env ?? process.env);
+	const workspace = await discoverWorkspace(root);
+	const graph = buildDependencyGraph(workspace.packages);
+	validateDependencyRangeShapes(graph);
+	const order = topologicalOrder(graph);
+	log(`${packageName}: ${order.length} packages in release order (gated -- tag only, publish deferred): ${order.join(" -> ")}`);
+	const publishPlugins = resolvePublishPlugins(options.plugins ?? DEFAULT_PUBLISH_PLUGINS, workspace.root, { requireGitPlugin: !dryRun });
+	const analyzeCommitsConfig = options.analyzeCommits ?? {};
+	const generateNotesConfig = options.generateNotes ?? {};
+	const entries = await runReleaseLoop(graph, order, workspace, dryRun, log, async (pkg, bumpsForThisPackage) => {
+		const state = await runPackageDetach(pkg, {
+			publishPlugins,
+			analyzeCommitsConfig,
+			generateNotesConfig,
+			bumpsForThisPackage,
+			dryRun,
+			env,
+			branches: options.branches
+		});
+		return {
+			released: state !== null,
+			version: state?.nextRelease.version,
+			result: state
+		};
+	});
+	return {
+		order,
+		packages: entries.map((entry) => ({
+			name: entry.name,
+			directory: entry.directory,
+			released: entry.result !== null,
+			version: entry.result?.nextRelease.version,
+			gitTag: entry.result?.nextRelease.gitTag,
+			type: entry.result?.nextRelease.type,
+			dependencyBumps: entry.dependencyBumps
+		})),
+		detached: entries.map((entry) => ({
+			name: entry.name,
+			relativeDirectory: entry.relativeDirectory,
+			state: entry.result,
+			dependencyBumps: entry.dependencyBumps
+		}))
+	};
+}
+async function runPackageDetach(pkg, options) {
+	const scoped = createScopedPlugins({
+		pkg,
+		analyzeCommitsConfig: options.analyzeCommitsConfig,
+		generateNotesConfig: options.generateNotesConfig,
+		bumps: { bumpsFor: () => options.bumpsForThisPackage }
+	});
+	const cliOptions = {
+		tagFormat: `${pkg.name}@\${version}`,
+		plugins: options.publishPlugins,
+		analyzeCommits: scoped.analyzeCommits,
+		generateNotes: scoped.generateNotes
+	};
+	if (options.dryRun) cliOptions.dryRun = true;
+	if (options.branches !== void 0) cliOptions.branches = options.branches;
+	try {
+		return await detachRelease(cliOptions, {
+			cwd: pkg.directory,
+			env: { ...options.env }
+		});
+	} catch (cause) {
+		throw new WorkspaceReleaseError(`Detaching ${pkg.name} failed: ${cause instanceof Error ? cause.message : String(cause)}`);
+	}
+}
+/**
+* Runtime guard for a `DetachedPackageRelease[]` read back off disk (the CLI's `resume` subcommand reads `WorkspaceReleaseOutcome.detached` from a JSON file `release --gate-publish` wrote) -- `JSON.parse` returns `any`, so this is the boundary that turns it back into something safe to pass to `resumeWorkspaceRelease`. Only checks the outer shape (`name`, `relativeDirectory`, `dependencyBumps`, and that `state` is either `null` or an object); `state`'s own inner shape is validated by `@exadev/release-gate`'s `resumeRelease` itself, once per entry, which is where a genuinely malformed state fails loudly with a specific error rather than here.
+*/
+function isDetachedPackageReleaseArray(value) {
+	if (!isUnknownArray(value)) return false;
+	return value.every((entry) => {
+		if (!isJsonObject(entry)) return false;
+		if (typeof entry.name !== "string" || typeof entry.relativeDirectory !== "string") return false;
+		if (entry.state !== null && !isJsonObject(entry.state)) return false;
+		return isUnknownArray(entry.dependencyBumps);
+	});
+}
+/**
+* Finishes every package a `gatePublish: true` `releaseWorkspace` run tagged and pushed but did not publish. Resumes each `detached` entry in the array's own order -- not re-derived from the workspace's dependency graph, since a resume pass may run in a separate process or checkout, where re-deriving order should only ever matter for directory lookup, not sequencing.
+*/
+async function resumeWorkspaceRelease(options) {
+	const root = resolve(options.root ?? process.cwd());
+	const log = options.log ?? console.log;
+	const env = sanitizeGitEnv(options.env ?? process.env);
+	const order = [];
+	const packages = [];
+	for (const entry of options.detached) {
+		order.push(entry.name);
+		if (entry.state === null) {
+			log(`${entry.name}: no release to resume`);
+			packages.push({
+				name: entry.name,
+				directory: resolve(root, entry.relativeDirectory),
+				released: false,
+				version: void 0,
+				gitTag: void 0,
+				type: void 0,
+				dependencyBumps: entry.dependencyBumps
+			});
+			continue;
+		}
+		const directory = resolve(root, entry.relativeDirectory);
+		log(`Resuming ${entry.name} from ${entry.relativeDirectory}`);
+		let releases;
+		try {
+			releases = await resumeRelease(entry.state, {
+				cwd: directory,
+				env: { ...env }
+			});
+		} catch (cause) {
+			throw new WorkspaceReleaseError(`Resuming ${entry.name} failed: ${cause instanceof Error ? cause.message : String(cause)}`);
+		}
+		log(`${entry.name}: published ${entry.state.nextRelease.gitTag} (${releases.length} publish plugin${releases.length === 1 ? "" : "s"} ran)`);
+		packages.push({
+			name: entry.name,
+			directory,
+			released: true,
+			version: entry.state.nextRelease.version,
+			gitTag: entry.state.nextRelease.gitTag,
+			type: entry.state.nextRelease.type,
+			dependencyBumps: entry.dependencyBumps
+		});
+	}
+	return {
+		order,
+		packages
+	};
+}
+//#endregion
 //#region src/cli.ts
 const CONFIG_OPTION_KEYS = /* @__PURE__ */ new Set([
 	"dryRun",
@@ -1164,7 +1331,8 @@ const CONFIG_OPTION_KEYS = /* @__PURE__ */ new Set([
 	"plugins",
 	"analyzeCommits",
 	"generateNotes",
-	"commitStrategy"
+	"commitStrategy",
+	"gatePublish"
 ]);
 const COMMIT_STRATEGIES = /* @__PURE__ */ new Set(["per-package", "single"]);
 function isCommitStrategy(value) {
@@ -1186,8 +1354,15 @@ function createProgram() {
 	release.option("--analyze-commits <json>", "options for the wrapped @semantic-release/commit-analyzer, as a JSON object");
 	release.option("--generate-notes <json>", "options for the wrapped @semantic-release/release-notes-generator, as a JSON object");
 	release.option("--commit-strategy <mode>", "how the run commits its released changes: \"per-package\" (default; today's behaviour, one commit per release plus one per dependency bump) or \"single\" (one combined commit for the whole run, tagged once per released package)", parseCommitStrategy);
-	release.option("--config <file>", "config file (.json, .yaml, .yml, .js, .cjs, or .ts) providing any of the release options (dryRun, branches, plugins, analyzeCommits, generateNotes, commitStrategy); explicit flags win");
+	release.option("--gate-publish", "tag and push each due package via @exadev/release-gate, but defer publishing -- requires --gate-state-file, and cannot be combined with --commit-strategy single");
+	release.option("--gate-state-file <path>", "with --gate-publish: where to write the state a later \"resume\" run needs to finish publishing");
+	release.option("--config <file>", "config file (.json, .yaml, .yml, .js, .cjs, or .ts) providing any of the release options (dryRun, branches, plugins, analyzeCommits, generateNotes, commitStrategy, gatePublish); explicit flags win");
 	release.action(runRelease);
+	const resume = program.command("resume");
+	resume.description("Finish publishing every package a --gate-publish release tagged and pushed but did not publish.");
+	resume.option("--root <directory>", "workspace root holding pnpm-workspace.yaml (this checkout, which may differ from the one that ran release --gate-publish)", process.cwd());
+	resume.requiredOption("--gate-state-file <path>", "the state file a \"release --gate-publish\" run wrote");
+	resume.action(runResume);
 	return program;
 }
 function parseCommitStrategy(value) {
@@ -1200,10 +1375,13 @@ const NO_CONFIG_FILE = {
 	plugins: void 0,
 	analyzeCommits: void 0,
 	generateNotes: void 0,
-	commitStrategy: void 0
+	commitStrategy: void 0,
+	gatePublish: void 0
 };
 async function runRelease(flags) {
 	const file = flags.config === void 0 ? NO_CONFIG_FILE : readReleaseConfigFile(flags.config);
+	const gatePublish = flags.gatePublish ?? file.gatePublish ?? false;
+	if (gatePublish && flags.gateStateFile === void 0) throw new InvalidArgumentError("--gate-publish requires --gate-state-file, since that is where the state a later \"resume\" run needs gets written");
 	const outcome = await releaseWorkspace({
 		root: flags.root,
 		dryRun: flags.dryRun ?? (file.dryRun === true ? true : void 0),
@@ -1211,7 +1389,23 @@ async function runRelease(flags) {
 		plugins: flags.plugin.length > 0 ? flags.plugin.map((spec) => parsePluginSpec(spec)) : file.plugins,
 		analyzeCommits: flags.analyzeCommits === void 0 ? file.analyzeCommits : parseJsonObjectFlag(flags.analyzeCommits, "--analyze-commits"),
 		generateNotes: flags.generateNotes === void 0 ? file.generateNotes : parseJsonObjectFlag(flags.generateNotes, "--generate-notes"),
-		commitStrategy: flags.commitStrategy ?? file.commitStrategy
+		commitStrategy: flags.commitStrategy ?? file.commitStrategy,
+		gatePublish
+	});
+	for (const pkg of outcome.packages) console.log(describeOutcome(pkg));
+	if (gatePublish) {
+		if (flags.gateStateFile === void 0) throw new WorkspaceReleaseError("gatePublish was true but no --gate-state-file was resolved -- this should be unreachable.");
+		await writeFile(flags.gateStateFile, JSON.stringify(outcome.detached ?? [], null, 2));
+		console.log(`${packageName}: wrote gate state for ${(outcome.detached ?? []).length} package(s) to ${flags.gateStateFile}`);
+	}
+}
+async function runResume(flags) {
+	const raw = await readFile(flags.gateStateFile, "utf8");
+	const parsed = JSON.parse(raw);
+	if (!isDetachedPackageReleaseArray(parsed)) throw new InvalidArgumentError(`--gate-state-file ${flags.gateStateFile} does not contain a valid gate state array`);
+	const outcome = await resumeWorkspaceRelease({
+		root: flags.root,
+		detached: parsed
 	});
 	for (const pkg of outcome.packages) console.log(describeOutcome(pkg));
 }
@@ -1257,20 +1451,22 @@ function readReleaseConfigFile(path) {
 	const parsed = readConfigFile(path);
 	if (!isJsonObject(parsed)) throw new InvalidArgumentError(`--config file ${path} must contain a JSON object`);
 	for (const key of Object.keys(parsed)) if (!CONFIG_OPTION_KEYS.has(key)) throw new InvalidArgumentError(`--config file ${path} has an unknown option "${key}"; recognised options: ${[...CONFIG_OPTION_KEYS].join(", ")}`);
-	const { dryRun, branches, plugins, analyzeCommits, generateNotes, commitStrategy } = parsed;
+	const { dryRun, branches, plugins, analyzeCommits, generateNotes, commitStrategy, gatePublish } = parsed;
 	if (dryRun !== void 0 && typeof dryRun !== "boolean") throw new InvalidArgumentError(`--config file ${path}: "dryRun" must be a boolean`);
 	if (branches !== void 0 && !isStringArray(branches)) throw new InvalidArgumentError(`--config file ${path}: "branches" must be an array of branch name strings`);
 	if (plugins !== void 0 && !Array.isArray(plugins)) throw new InvalidArgumentError(`--config file ${path}: "plugins" must be an array`);
 	if (analyzeCommits !== void 0 && !isJsonObject(analyzeCommits)) throw new InvalidArgumentError(`--config file ${path}: "analyzeCommits" must be an object`);
 	if (generateNotes !== void 0 && !isJsonObject(generateNotes)) throw new InvalidArgumentError(`--config file ${path}: "generateNotes" must be an object`);
 	if (commitStrategy !== void 0 && (typeof commitStrategy !== "string" || !isCommitStrategy(commitStrategy))) throw new InvalidArgumentError(`--config file ${path}: "commitStrategy" must be one of: ${[...COMMIT_STRATEGIES].join(", ")}`);
+	if (gatePublish !== void 0 && typeof gatePublish !== "boolean") throw new InvalidArgumentError(`--config file ${path}: "gatePublish" must be a boolean`);
 	return {
 		dryRun,
 		branches,
 		plugins: plugins === void 0 ? void 0 : plugins.map((spec) => parseConfigFilePlugin(spec, path)),
 		analyzeCommits,
 		generateNotes,
-		commitStrategy
+		commitStrategy,
+		gatePublish
 	};
 }
 function parseConfigFilePlugin(spec, path) {