@fuzdev/fuz_gitops 0.72.0 → 0.73.0

package/src/lib/operations.ts

@@ -39,7 +39,7 @@ import type {FsError} from '@fuzdev/fuz_util/fs.js';
 import type {Logger} from '@fuzdev/fuz_util/log.js';
 import type {LocalRepo} from './local_repo.js';
 import type {ChangesetInfo} from './changeset_reader.js';
-import type {BumpType} from './semver.js';
+import type {BumpType} from './version_utils.js';
 import type {PreflightOptions, PreflightResult} from './preflight_checks.js';
 import type {WaitOptions} from './npm_registry.js';
 
@@ -156,16 +156,15 @@ export interface GitOperations {
 	}) => Promise<Result<object, {message: string}>>;
 
 	/**
-	 * Checks if there are any uncommitted changes.
+	 * Checks whether the working tree has any changes — staged, unstaged, or
+	 * untracked (`git status --porcelain`). Broader than `list_uncommitted_files`,
+	 * which reports only tracked working-tree changes relative to HEAD.
 	 */
 	has_changes: (options?: {cwd?: string}) => Promise<Result<{value: boolean}, {message: string}>>;
 
 	/**
-	 * Lists uncommitted files in the working tree (`git diff --name-only HEAD`).
-	 *
-	 * Renamed from `get_changed_files` in 2026-04 because "changed files" collided
-	 * with mageguild's `get_changed_files` which diffs two refs. This one reports
-	 * uncommitted working-tree changes relative to HEAD.
+	 * Lists uncommitted files in the working tree (`git diff --name-only HEAD`),
+	 * i.e. working-tree changes relative to HEAD (not a diff between two refs).
 	 */
 	list_uncommitted_files: (options?: {
 		cwd?: string;
@@ -253,15 +252,6 @@ export interface NpmOperations {
 		log?: Logger;
 	}) => Promise<Result<object, {message: string; timeout?: boolean}>>;
 
-	/**
-	 * Checks if a package version is available on NPM.
-	 */
-	check_package_available: (options: {
-		pkg: string;
-		version: string;
-		log?: Logger;
-	}) => Promise<Result<{value: boolean}, {message: string}>>;
-
 	/**
 	 * Checks npm authentication status.
 	 */
@@ -278,12 +268,6 @@ export interface NpmOperations {
 	install: (options?: {
 		cwd?: string;
 	}) => Promise<Result<object, {message: string; stderr?: string}>>;
-
-	/**
-	 * Cleans the npm cache.
-	 * Uses `npm cache clean --force` to clear stale cache entries.
-	 */
-	cache_clean: () => Promise<Result<object, {message: string}>>;
 }
 
 /**

package/src/lib/operations_defaults.ts

@@ -14,7 +14,7 @@ import {fs_classify_error} from '@fuzdev/fuz_util/fs.js';
 import {EMPTY_OBJECT} from '@fuzdev/fuz_util/object.js';
 
 import {has_changesets, read_changesets, predict_next_version} from './changeset_reader.js';
-import {wait_for_package, check_package_available} from './npm_registry.js';
+import {wait_for_package} from './npm_registry.js';
 import {run_preflight_checks} from './preflight_checks.js';
 import {
 	git_add,
@@ -236,11 +236,6 @@ export const default_npm_operations: NpmOperations = {
 		}
 	},
 
-	check_package_available: async (options) => {
-		const {pkg, version, log} = options;
-		return wrap_with_value(() => check_package_available(pkg, version, {log}));
-	},
-
 	check_auth: async () => {
 		try {
 			const result = await spawn_out('npm', ['whoami']);
@@ -281,19 +276,6 @@ export const default_npm_operations: NpmOperations = {
 			return {ok: false, message: String(error)};
 		}
 	},
-
-	cache_clean: async () => {
-		try {
-			const spawned = await spawn_out('npm', ['cache', 'clean', '--force']);
-			if (spawned.result.ok) {
-				return {ok: true};
-			} else {
-				return {ok: false, message: 'Cache clean failed'};
-			}
-		} catch (error) {
-			return {ok: false, message: String(error)};
-		}
-	},
 };
 
 export const default_preflight_operations: PreflightOperations = {

package/src/lib/output_helpers.ts

@@ -50,15 +50,16 @@ export const format_and_output = async <T>(
 	// Format data
 	const content = format === 'json' ? formatters.json(data) : formatters.markdown(data).join('\n');
 
-	// Output to file or log
+	// Output to file or stdout
 	if (outfile) {
 		await writeFile(outfile, content);
 		log?.info(`Output written to ${outfile}`);
 	} else {
-		// Log line by line for better formatting
-		const lines = content.split('\n');
-		for (const line of lines) {
-			log?.info(line);
-		}
+		// Write raw to stdout in one shot. Routing through `log` would prefix every
+		// line with `[taskname]`, corrupting JSON and cluttering markdown — keep the
+		// machine-readable formats unprefixed and pipeable (use `--outfile` for output
+		// fully free of Gro's own preamble).
+		// eslint-disable-next-line no-console
+		console.log(content);
 	}
 };

package/src/lib/paths.ts

@@ -1,8 +1,3 @@
-/**
- * Base directory for all gitops-generated files.
- */
-export const GITOPS_OUTPUT_DIR = '.gro/fuz_gitops';
-
 /**
  * Default repos directory relative to gitops config file.
  * Resolves to the parent of the directory with the config

package/src/lib/publish_gate.ts

@@ -0,0 +1,53 @@
+/**
+ * Pure decision logic for the `gitops_publish` task's interactive gating.
+ *
+ * Extracted from `gitops_publish.task.ts` so the gating table is unit-testable without driving
+ * readline or `process.exit`. The task keeps the IO — prompt, exit, logging — at its edge and
+ * consults these for every branch.
+ *
+ * @module
+ */
+
+import type {PublishingResult} from './multi_repo_publisher.js';
+import type {PublishingPlan} from './publishing_plan.js';
+
+/** What the task should do with a generated plan before executing the cascade. */
+export type PublishGate =
+	| {action: 'blocked'; message: string}
+	| {action: 'confirm'}
+	| {action: 'proceed'};
+
+export interface PublishGateOptions {
+	/** A real publish (`--wetrun`); a dry run never prompts. */
+	wetrun: boolean;
+	/** Show the plan and confirm (`plan`); `--no-plan` skips the prompt. */
+	show_plan: boolean;
+	plan: Pick<PublishingPlan, 'errors'>;
+}
+
+/**
+ * Decides whether a publish run must block, prompt for confirmation, or proceed without
+ * prompting, from the pre-execution inputs.
+ *
+ * - `blocked`: a real publish whose plan has errors — fail loud before prompting. The executor
+ *   enforces this too, so `--no-plan` can't bypass the gate; this branch only avoids prompting
+ *   for (and printing the "this will publish" banner of) a plan that can't run.
+ * - `confirm`: a real publish that shows its plan — the user must confirm interactively.
+ * - `proceed`: a dry run, or a `--no-plan` real publish — no prompt.
+ */
+export const decide_publish_gate = (options: PublishGateOptions): PublishGate => {
+	if (!options.wetrun || !options.show_plan) return {action: 'proceed'};
+	if (options.plan.errors.length > 0) {
+		return {action: 'blocked', message: 'Cannot proceed with publishing due to errors'};
+	}
+	return {action: 'confirm'};
+};
+
+/**
+ * Whether a finished run should exit non-zero: an unsuccessful result, or a fatal error thrown
+ * out of the executor.
+ */
+export const publish_run_failed = (
+	result: Pick<PublishingResult, 'ok'>,
+	fatal_error: Error | null,
+): boolean => !result.ok || fatal_error !== null;

package/src/lib/publish_steps.ts

@@ -0,0 +1,149 @@
+/**
+ * Side-effect preview for a publishing plan.
+ *
+ * `derive_publish_steps` linearizes a frozen `PublishingPlan` into the ordered side-effects
+ * a `--wetrun` would perform, mirroring `execute_publishing_plan`'s pass so the preview and
+ * the executor read the same plan data and can't drift. Pure — no side effects.
+ *
+ * @module
+ */
+
+import type {BumpType} from './version_utils.js';
+import type {PublishingPlan, VersionChange} from './publishing_plan.js';
+import {UnreachableError} from '@fuzdev/fuz_util/error.js';
+
+/** How a package's version bump arises in the plan. */
+export type PublishStepVia = 'changeset' | 'auto_changeset' | 'escalation';
+
+/** One ordered side-effect a wetrun would perform. */
+export type PublishStep =
+	| {kind: 'publish'; repo: string; from: string; to: string; bump: BumpType; via: PublishStepVia}
+	| {kind: 'npm_wait'; repo: string; version: string}
+	| {
+			kind: 'dependency_update';
+			dependent: string;
+			dependency: string;
+			to: string;
+			dep_type: 'prod' | 'peer';
+			creates_changeset: boolean;
+	  }
+	| {kind: 'dev_dep_update'; repo: string; dependency: string; to: string}
+	| {kind: 'deploy'; repo: string; builds: boolean};
+
+export interface DerivePublishStepsOptions {
+	/** Include the deploy phase (the publisher only deploys with `--deploy`). */
+	deploy?: boolean;
+}
+
+const step_via = (change: VersionChange): PublishStepVia =>
+	change.needs_bump_escalation
+		? 'escalation'
+		: change.has_changesets
+			? 'changeset'
+			: 'auto_changeset';
+
+/**
+ * Derives the ordered side-effects a wetrun would perform from a frozen plan.
+ *
+ * Reads only `publishing_order`, `version_changes`, and `dependency_updates` — the same data
+ * `execute_publishing_plan` consumes, in the same order — so the preview reflects the real
+ * pass. A dependency is only propagated to its dependents if it actually publishes this run.
+ */
+export const derive_publish_steps = (
+	plan: PublishingPlan,
+	options: DerivePublishStepsOptions = {},
+): Array<PublishStep> => {
+	const {deploy = false} = options;
+	const changes: Map<string, VersionChange> = new Map(
+		plan.version_changes.map((vc) => [vc.package_name, vc]),
+	);
+
+	const steps: Array<PublishStep> = [];
+	const changed: Set<string> = new Set(); // for the deploy phase: published + their dependents
+
+	// Phase 1: one pass over the topological order, mirroring `execute_publishing_plan`.
+	for (const repo of plan.publishing_order) {
+		const change = changes.get(repo);
+		if (!change) continue; // not in the plan = nothing to publish
+
+		steps.push({
+			kind: 'publish',
+			repo,
+			from: change.from,
+			to: change.to,
+			bump: change.bump_type,
+			via: step_via(change),
+		});
+		steps.push({kind: 'npm_wait', repo, version: change.to});
+		changed.add(repo);
+
+		// Prod/peer dependents are rewritten right after this publishes. A dependent that
+		// republishes (has its own plan version change) gets an auto-changeset and republishes in
+		// turn (its rewritten deps are installed + healed by its own `gro publish`); a private
+		// dependent has no version change, so it's an update-only leaf — range rewritten, no
+		// changeset.
+		for (const update of plan.dependency_updates) {
+			if (update.updated_dependency !== repo) continue;
+			if (update.type !== 'dependencies' && update.type !== 'peerDependencies') continue;
+			const republishes = changes.has(update.dependent_package);
+			steps.push({
+				kind: 'dependency_update',
+				dependent: update.dependent_package,
+				dependency: repo,
+				to: change.to,
+				dep_type: update.type === 'peerDependencies' ? 'peer' : 'prod',
+				creates_changeset: republishes,
+			});
+			changed.add(update.dependent_package);
+		}
+	}
+
+	// Phase 2: dev-dependency updates for deps that published this run — committed without a
+	// changeset (dev-only changes redeploy, they don't republish). No install step: these repos
+	// don't run `gro publish`; gro installs + heals their deps when they next build/deploy/sync.
+	for (const update of plan.dependency_updates) {
+		if (update.type !== 'devDependencies') continue;
+		const dep_change = changes.get(update.updated_dependency);
+		if (!dep_change) continue;
+		steps.push({
+			kind: 'dev_dep_update',
+			repo: update.dependent_package,
+			dependency: update.updated_dependency,
+			to: dep_change.to,
+		});
+		changed.add(update.dependent_package);
+	}
+
+	// Phase 3: deploy every changed repo (only with --deploy). Each builds fresh.
+	if (deploy) {
+		for (const repo of changed) {
+			steps.push({kind: 'deploy', repo, builds: true});
+		}
+	}
+
+	return steps;
+};
+
+/**
+ * Formats steps as human-readable lines (one per step) for stdout and markdown output.
+ * Returns a single placeholder line when there are no side effects.
+ */
+export const format_publish_steps = (steps: Array<PublishStep>): Array<string> => {
+	if (steps.length === 0) return ['(no side effects — nothing to publish)'];
+	return steps.map((step) => {
+		switch (step.kind) {
+			case 'publish':
+				return `publish   ${step.repo}  ${step.from} → ${step.to}  (${step.bump}, ${step.via})`;
+			case 'npm_wait':
+				return `npm wait  ${step.repo}@${step.version}`;
+			case 'dependency_update':
+				return `update    ${step.dependent} ← ${step.dependency}@${step.to}  (${step.dep_type}${step.creates_changeset ? ', changeset' : ''})`;
+			case 'dev_dep_update':
+				return `dev dep   ${step.repo} ← ${step.dependency}@${step.to}  (no changeset)`;
+			case 'deploy':
+				return `deploy    ${step.repo}${step.builds ? '  (builds)' : ''}`;
+			default:
+				throw new UnreachableError(step);
+		}
+	});
+};

package/src/lib/publishing_event.ts

@@ -26,6 +26,10 @@ export const PublishingErrorCode = z.enum([
 	'auth',
 	'dependency',
 	'build',
+	// the real published version diverged from the frozen plan's prediction — an
+	// invariant violation, distinct from an ordinary publish failure (see fail-loud
+	// drift detection in `multi_repo_publisher.ts`)
+	'drift',
 	'other',
 ]);
 export type PublishingErrorCode = z.infer<typeof PublishingErrorCode>;
@@ -50,17 +54,6 @@ export const PublishingEvent = z.discriminatedUnion('event', [
 		wetrun: z.boolean().meta({description: 'false means every package_completed is a prediction'}),
 		total: z.number(),
 	}),
-	z.strictObject({
-		event: z.literal('iteration_started'),
-		iteration: z.number(),
-		max: z.number(),
-	}),
-	z.strictObject({
-		event: z.literal('iteration_finished'),
-		iteration: z.number(),
-		published_count: z.number(),
-		converged: z.boolean(),
-	}),
 	z.strictObject({
 		event: z.literal('package_skipped'),
 		name: z.string(),
@@ -71,12 +64,17 @@ export const PublishingEvent = z.discriminatedUnion('event', [
 		name: z.string(),
 		old_version: z.string(),
 		new_version: z.string(),
-		// mirrors `BumpType` from `semver.ts`; inline so the event schema is self-contained
+		// mirrors `BumpType` from `version_utils.ts`; inline so the event schema is self-contained
 		bump_type: z.enum(['major', 'minor', 'patch']),
 		breaking: z.boolean(),
 		commit: z.string().meta({description: "'simulated' in a dry run, otherwise the commit hash"}),
 		tag: z.string(),
 	}),
+	z.strictObject({
+		event: z.literal('npm_waited'),
+		name: z.string(),
+		version: z.string().meta({description: 'the version waited on after publishing'}),
+	}),
 	z.strictObject({
 		event: z.literal('package_failed'),
 		name: z.string(),
@@ -88,19 +86,12 @@ export const PublishingEvent = z.discriminatedUnion('event', [
 		dependent: z.string(),
 		dependency: z.string(),
 		version: z.string(),
-	}),
-	z.strictObject({
-		event: z.literal('install_started'),
-		name: z.string(),
-	}),
-	z.strictObject({
-		event: z.literal('install_completed'),
-		name: z.string(),
-	}),
-	z.strictObject({
-		event: z.literal('install_failed'),
-		name: z.string(),
-		error: z.string(),
+		// 'prod'/'peer' updates run inline in the publish pass; 'dev' updates run in the later
+		// dev-dependency pass. Lets a consumer reconstruct which side-effect phase this is.
+		dep_type: z.enum(['prod', 'peer', 'dev']),
+		// true when the update creates an auto-changeset (a publishable dependent republishes);
+		// false for dev-dep updates and update-only leaves (private dependents never publish).
+		creates_changeset: z.boolean(),
 	}),
 	z.strictObject({
 		event: z.literal('deploy_started'),

package/src/lib/publishing_plan.ts

@@ -2,9 +2,13 @@ import type {Logger} from '@fuzdev/fuz_util/log.js';
 import {styleText as st} from 'node:util';
 
 import type {LocalRepo} from './local_repo.js';
-import type {BumpType} from './semver.js';
 import {validate_dependency_graph} from './graph_validation.js';
-import {is_breaking_change, compare_bump_types, calculate_next_version} from './version_utils.js';
+import {
+	type BumpType,
+	is_breaking_change,
+	compare_bump_types,
+	calculate_next_version,
+} from './version_utils.js';
 import type {ChangesetOperations} from './operations.js';
 import {default_changeset_operations} from './operations_defaults.js';
 import {GITOPS_MAX_ITERATIONS_DEFAULT} from './gitops_constants.js';
@@ -36,7 +40,6 @@ export interface DependencyUpdate {
 	current_version: string;
 	new_version: string;
 	type: 'dependencies' | 'devDependencies' | 'peerDependencies';
-	causes_republish: boolean;
 }
 
 // Verbose data types for diagnostic output
@@ -178,6 +181,18 @@ export const generate_publishing_plan = async (
 		const repo = repos.find((r) => r.library.name === pkg_name);
 		if (!repo) continue;
 
+		// Private packages never publish — exclude them from version changes entirely (no
+		// publish step, npm-wait, bump escalation, or auto-changeset). They keep their slot in
+		// the topological order. Flag a private package that carries a changeset, since that
+		// changeset can't be published.
+		if (repo.library.package_json.private) {
+			const private_has_changesets = await ops.has_changesets({repo});
+			if (private_has_changesets.ok && private_has_changesets.value) {
+				warnings.push(`${pkg_name} is private — its changeset(s) will not be published`);
+			}
+			continue;
+		}
+
 		// Check for changesets
 		const has_result = await ops.has_changesets({repo});
 
@@ -267,6 +282,10 @@ export const generate_publishing_plan = async (
 		for (const repo of repos) {
 			const pkg_name = repo.library.name;
 
+			// Private packages are excluded from version changes (they never publish), so they
+			// never escalate or auto-generate a changeset.
+			if (repo.library.package_json.private) continue;
+
 			// Get required bump from dependencies
 			const required_bump = get_required_bump_for_dependencies(
 				repo,
@@ -405,6 +424,7 @@ export const generate_publishing_plan = async (
 
 		for (const repo of repos) {
 			const pkg_name = repo.library.name;
+			if (repo.library.package_json.private) continue; // private packages never publish
 			const required_bump = get_required_bump_for_dependencies(
 				repo,
 				pending_updates,

package/src/lib/publishing_plan_helpers.ts

@@ -7,8 +7,7 @@
  */
 
 import type {LocalRepo} from './local_repo.js';
-import type {BumpType} from './semver.js';
-import {needs_update} from './version_utils.js';
+import {needs_update, required_bump_for_dependency_update, type BumpType} from './version_utils.js';
 import type {DependencyUpdate} from './publishing_plan.js';
 
 /**
@@ -42,7 +41,6 @@ export const calculate_dependency_updates = (
 						current_version,
 						new_version,
 						type: 'dependencies',
-						causes_republish: true,
 					});
 
 					if (breaking_packages.has(dep_name)) {
@@ -67,7 +65,6 @@ export const calculate_dependency_updates = (
 						current_version,
 						new_version,
 						type: 'peerDependencies',
-						causes_republish: true,
 					});
 
 					if (breaking_packages.has(dep_name)) {
@@ -92,7 +89,6 @@ export const calculate_dependency_updates = (
 						current_version,
 						new_version,
 						type: 'devDependencies',
-						causes_republish: false,
 					});
 				}
 			}
@@ -131,17 +127,8 @@ export const get_required_bump_for_dependencies = (
 		breaking_packages.has(update.updated_dependency),
 	);
 
-	const current_version = repo.library.package_json.version || '0.0.0';
-	const [major] = current_version.split('.').map(Number);
-	const is_pre_1_0 = major === 0;
-
-	if (has_breaking_deps) {
-		// Breaking changes propagate
-		// Pre-1.0: use minor for breaking changes
-		// 1.0+: use major for breaking changes
-		return is_pre_1_0 ? 'minor' : 'major';
-	}
-
-	// For non-breaking dependency updates, use patch
-	return 'patch';
+	return required_bump_for_dependency_update(
+		repo.library.package_json.version || '0.0.0',
+		has_breaking_deps,
+	);
 };

package/src/lib/publishing_plan_logging.ts

@@ -182,54 +182,34 @@ export const log_publishing_plan = (
 		const with_escalation = ordered_changes.filter((vc) => vc.needs_bump_escalation);
 		const with_auto_changesets = ordered_changes.filter((vc) => vc.will_generate_changeset);
 
-		// Log each group with diff-style output
-		if (with_changesets.length > 0) {
-			log.info(st('cyan', 'Version Changes (from changesets):'));
-			for (const change of with_changesets) {
-				const idx = ordered_changes.indexOf(change);
+		// A single running counter across all groups so positions read 1..N with no
+		// gaps. (Numbering per-group index would make the first group skip the numbers
+		// that land in a later group, e.g. jump from `[9/12]` to `[11/12]`.)
+		const total = with_changesets.length + with_escalation.length + with_auto_changesets.length;
+		let position = 0;
+		const log_change_group = (
+			title: string,
+			color: 'cyan' | 'yellow',
+			changes: Array<VersionChange>,
+		): void => {
+			if (changes.length === 0) return;
+			log.info(st(color, title));
+			for (const change of changes) {
 				log_version_change_with_diffs(
 					change,
-					idx,
-					ordered_changes.length,
+					position++,
+					total,
 					dependency_updates,
 					breaking_cascades,
 					log,
 				);
 			}
 			log.info('');
-		}
-
-		if (with_escalation.length > 0) {
-			log.info(st('yellow', 'Version Changes (bump escalation):'));
-			for (const change of with_escalation) {
-				const idx = ordered_changes.indexOf(change);
-				log_version_change_with_diffs(
-					change,
-					idx,
-					ordered_changes.length,
-					dependency_updates,
-					breaking_cascades,
-					log,
-				);
-			}
-			log.info('');
-		}
+		};
 
-		if (with_auto_changesets.length > 0) {
-			log.info(st('cyan', 'Version Changes (auto-generated):'));
-			for (const change of with_auto_changesets) {
-				const idx = ordered_changes.indexOf(change);
-				log_version_change_with_diffs(
-					change,
-					idx,
-					ordered_changes.length,
-					dependency_updates,
-					breaking_cascades,
-					log,
-				);
-			}
-			log.info('');
-		}
+		log_change_group('Version Changes (from changesets):', 'cyan', with_changesets);
+		log_change_group('Version Changes (bump escalation):', 'yellow', with_escalation);
+		log_change_group('Version Changes (auto-generated):', 'cyan', with_auto_changesets);
 	} else {
 		log.info(st('dim', 'No packages to publish'));
 		log.info('');

package/src/lib/version_utils.ts

@@ -1,6 +1,7 @@
 // TODO: candidate for extraction to `@fuzdev/fuz_util`
 
-import type {BumpType} from './semver.js';
+/** A semver bump kind: `major`, `minor`, or `patch`. */
+export type BumpType = 'major' | 'minor' | 'patch';
 
 export const is_wildcard = (version: string): boolean => {
 	return version === '*';
@@ -100,10 +101,7 @@ export const get_update_prefix = (
  * Pre-1.0: minor bumps are breaking
  * 1.0+: major bumps are breaking
  */
-export const is_breaking_change = (
-	old_version: string,
-	bump_type: 'major' | 'minor' | 'patch',
-): boolean => {
+export const is_breaking_change = (old_version: string, bump_type: BumpType): boolean => {
 	const [major] = old_version.split('.').map(Number);
 	const is_pre_1_0 = major === 0;
 
@@ -116,10 +114,33 @@ export const is_breaking_change = (
 	}
 };
 
-export const detect_bump_type = (
-	old_version: string,
-	new_version: string,
-): 'major' | 'minor' | 'patch' => {
+/**
+ * The bump a package must take when one of its prod/peer dependencies updates.
+ * Pre-1.0: `minor` for a breaking dependency, otherwise `patch`.
+ * 1.0+: `major` for a breaking dependency, otherwise `patch`.
+ *
+ * Single source of truth for the dependency-driven bump rule, shared by the plan
+ * (`get_required_bump_for_dependencies`) and the auto-changeset generator
+ * (`calculate_required_bump`) so the two never drift.
+ *
+ * @param current_version - the package's current version, used to detect the pre-1.0 regime
+ * @param has_breaking_deps - whether any updated dependency is a breaking change
+ */
+export const required_bump_for_dependency_update = (
+	current_version: string,
+	has_breaking_deps: boolean,
+): BumpType => {
+	const [major] = current_version.split('.').map(Number);
+	const is_pre_1_0 = major === 0;
+	if (has_breaking_deps) {
+		// Breaking changes propagate: pre-1.0 uses minor, 1.0+ uses major
+		return is_pre_1_0 ? 'minor' : 'major';
+	}
+	// Non-breaking dependency updates only need a patch
+	return 'patch';
+};
+
+export const detect_bump_type = (old_version: string, new_version: string): BumpType => {
 	const old_parts = old_version.split('.').map(Number);
 	const new_parts = new_version.split('.').map(Number);