feat: add plugin upgrade command for dynamic plugin dependency management

CHANGELOG.md

@@ -4,6 +4,12 @@ All notable changes to `@red-hat-developer-hub/cli` are documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## 2.0.6 - 2026-09-11
+
+### Added
+
+- **`plugin upgrade`:** Add `rhdh-cli plugin upgrade <version>` (alias `plugin versions:bump`) command ([RHIDP-16666](https://redhat.atlassian.net/browse/RHIDP-16666)). Automatically aligns all `@backstage/*` package dependencies in `package.json` (`dependencies`, `devDependencies`, `peerDependencies`) and `backstage.json` to the exact manifest versions for a target RHDH release, preserving range specifiers and non-manifest dependencies. Supports `--dry-run`, `--skip-install`, and offline `--manifest-file` options.
+
 ## 2.0.5 - 2026-09-04
 
 ### Added

README.md

@@ -43,6 +43,20 @@ For air-gapped environments, provide a local release manifest with `--manifest-f
 
 When adding support for a new RHDH release, update `RHDH_COMPATIBILITY_MATRIX` in `src/lib/rhdhVersion.ts` with its Backstage version before releasing the corresponding CLI version. This matrix is maintained manually until its release metadata can be automated.
 
+## Upgrading Plugin Versions
+
+Use `plugin upgrade` to update a plugin's `@backstage/*` dependencies to the versions from an RHDH release manifest:
+
+```bash
+rhdh-cli plugin upgrade --rhdh-version 2.0.0
+```
+
+The command also accepts the RHDH version as a positional argument, for example `rhdh-cli plugin upgrade 2.0.0`. Its `plugin versions:bump` alias provides the same behavior.
+
+Use `--dry-run` to preview dependency changes without writing files and `--skip-install` to avoid updating the lockfile after applying changes. Use `--json` for machine-readable output.
+
+For air-gapped environments, provide a local Backstage release manifest with `--manifest-file` and set `RHDH_OFFLINE=true` to skip the RHDH GitHub metadata lookup.
+
 ## Development
 
 ### Contributing

package.json

@@ -1,7 +1,7 @@
 {
   "name": "@red-hat-developer-hub/cli",
   "description": "CLI for developing Backstage plugins and apps",
-  "version": "2.0.5",
+  "version": "2.0.6",
   "publishConfig": {
     "access": "public"
   },

src/commands/check-versions/command.ts

@@ -22,6 +22,7 @@ import semver from 'semver';
 
 import { ExitCodeError } from '../../lib/errors';
 import { paths } from '../../lib/paths';
+import { DependencySection } from '../../lib/pluginDependencies';
 import { resolveRhdhVersion } from '../../lib/rhdhVersion';
 import { Task } from '../../lib/tasks';
 
@@ -30,10 +31,6 @@ export type DependencyStatus =
   | 'mismatch'
   | 'unmanifested'
   | 'unverifiable';
-export type DependencySection =
-  | 'dependencies'
-  | 'devDependencies'
-  | 'peerDependencies';
 
 export interface PackageCheckResult {
   name: string;

src/commands/index.ts

@@ -162,6 +162,31 @@ export function registerPluginCommand(program: Command) {
     )
     .option('--json', 'Output results as JSON')
     .action(lazy(() => import('./check-versions').then(m => m.command)));
+
+  command
+    .command('upgrade [rhdhVersion]')
+    .alias('versions:bump')
+    .description(
+      'Upgrade dynamic plugin dependencies in package.json to match a target RHDH release',
+    )
+    .option(
+      '--rhdh-version <version>',
+      'Target RHDH version to upgrade compatibility to (e.g. 2.0.0, 1.9, latest, backstage:1.54.0)',
+    )
+    .option(
+      '--dry-run',
+      'Display planned dependency updates without modifying files on disk',
+    )
+    .option(
+      '--skip-install',
+      'Do not run package manager install after updating dependencies',
+    )
+    .option(
+      '--manifest-file <path>',
+      'Path to local Backstage release manifest JSON file (for offline usage)',
+    )
+    .option('--json', 'Output upgrade results as JSON')
+    .action(lazy(() => import('./upgrade').then(m => m.command)));
 }
 
 export function registerCommands(program: Command) {