docs(plugin): add comprehensive dynamic plugin development guide

[gashcrumb]

Summary

Consolidates and refactors developer-facing documentation across all dynamic plugin development and on-ramp commands in rhdh-cli, fulfilling the documentation deliverables of RHIDP-16669 and RHIDP-13614.

Highlights

• New Guide (docs/Plugin-Development-CLI.md):
  • Overview & Architecture: Standalone dynamic plugin development without a Backstage host app, 5-minute on-ramp workflow.
  • plugin new: Standalone scaffolding, NFS frontend/backend/catalog-processor module types, upstream @backstage/cli-module-new template reuse, and local dev/ harnesses.
  • plugin check-versions (alias plugin versions:lint): 3-tier RHDH-to-Backstage version resolution, audit statuses (match, mismatch, unmanifested, unverifiable), exit codes, and CI pipeline recipes.
  • plugin upgrade (alias plugin versions:bump): Targeted upgrades, --dry-run previews, --skip-install, range specifier preservation (^, ~), and lockfile synchronization for Yarn and npm.
  • plugin dev: Local containerized runtime lifecycle (start, update, restart, stop, logs, status), configuration automation via --configure, and continuous watch mode (--watch).
  • Export & Packaging: Dynamic plugin export (plugin export) and container packaging (plugin package).
  • Air-Gapped & Offline: Working with --manifest-file and RHDH_OFFLINE=true.
• README.md Refactoring:
  • Added links to the new guide from all plugin development sections.
  • Updated the command overview to list all plugin development commands (plugin new, plugin dev, plugin check-versions, plugin upgrade, plugin export, plugin package).

[gashcrumb]

/fs-review

[fullsend-ai-review]

🤖 Finished Review · ✅ Success · Started 6:25 PM UTC · Completed 6:40 PM UTC

Commit: 66ff69b · View workflow run →

Runtime: claude · Model: sonnet → claude-sonnet-4-6 · Effort: high · Cost: $4.18

[fullsend-ai-review]

Risk Assessment: moderate (2/5)

Details

Pure documentation PR by an established contributor with no source, CI, or dependency changes; moderate line count elevates one Tier 1 signal but the docs-only scope and no regression history keep the composite at moderate, consistent with the prior assessment.

Previous run

Risk Assessment: moderate (2/5)

Details

Pure documentation PR by an established contributor with no source, CI, or dependency changes; moderate line count elevates Tier 1 slightly, but docs-only scope and no regression history on the new file keep the composite risk low-moderate.

[fullsend-ai-review]

Review

Findings

High

• [api-contract] docs/Plugin-Development-CLI.md:57 — plugin versions:lint is documented as an alias for plugin check-versions in the command summary table (line 57), the syntax block (line 137), the code fence (line 219), and README.md (lines 45, 60, 154), but no such alias is registered in src/commands/index.ts. The check-versions command (lines 135–148) has no .alias() call; only upgrade has .alias('versions:bump') at line 152. Running rhdh-cli plugin versions:lint will fail with an unknown-command error.
  Remediation: Either add .alias('versions:lint') to the check-versions command in src/commands/index.ts (after line 148, before .action()), or remove all versions:lint alias references from docs/Plugin-Development-CLI.md (lines 57, 137, 219) and README.md (lines 45, 60, 154).

Low

• [logic-error] docs/Plugin-Development-CLI.md:163 — The plugin new Syntax & Options section lists 7 options but omits --manifest-file <path>, which is registered in src/commands/index.ts (line 201) for plugin new and is required for air-gapped scaffolding. The Air-Gapped section at the bottom of the doc also omits plugin new from its --manifest-file examples (only check-versions and upgrade are shown). A user in an air-gapped environment would not discover this option from the guide.
  Remediation: Add --manifest-file <path> to the plugin new options list with a description matching the other commands (e.g. "Path to a local Backstage release manifest JSON file for air-gapped/offline scaffolding"). Also add a plugin new usage example in the Air-Gapped section.

• [incorrect-doc] docs/Plugin-Development-CLI.md:394 — The four progress-phase labels use imperative wording without ellipsis ([1/4] Build and export plugin, [4/4] Wait for RHDH readiness), but the CLI actually prints gerund phrases with trailing ellipsis: [1/4] Building and exporting plugin..., [2/4] Starting RHDH Local runtime..., [3/4] Installing dynamic plugins..., [4/4] Waiting for RHDH to be ready... (src/commands/dev/command.ts lines 256–266). All four labels differ in verb form and punctuation; the fourth also differs in wording.
  Remediation: Update the four phase labels to match the exact strings from src/commands/dev/command.ts lines 256–266.

---

Next steps:

• /fs-fix — agent addresses review findings automatically
• /fs-fix <your instruction> — agent fixes with your specific guidance
• Push commits directly — review re-runs automatically on push
• /fs-fix-stop — disable automatic fix runs for this PR

Previous run

Review

Findings

High

• [api-contract] docs/Plugin-Development-CLI.md:57 — plugin versions:lint is documented as an alias for plugin check-versions in the command summary table (line 57), the syntax block (line 136), and README.md (lines 45 and 154), but no such alias is registered in src/commands/index.ts. The check-versions command (lines 135–148) has no .alias() call; only upgrade has .alias('versions:bump') at line 152. Running rhdh-cli plugin versions:lint will fail with an unknown command error.
  Remediation: Either add .alias('versions:lint') to the check-versions command registration in src/commands/index.ts, or remove all versions:lint alias references from docs/Plugin-Development-CLI.md (lines 57, 136) and README.md (lines 45, 154).

Medium

• [logic-error] docs/Plugin-Development-CLI.md:295 — The stop subcommand row says --clean removes "networks/staged files". The actual implementation runs compose down (via composeArgs('clean')) which removes containers and the default network but explicitly does not remove staged plugin files in local-plugins/. The code's own log message (line 677 of src/commands/dev/command.ts) reads: "without removing volumes, configuration, or dynamic plugin artifacts."
  Remediation: Change the description to: "Stop RHDH Local runtime containers; add --clean to also remove containers and networks (volumes, configuration, and staged plugin artifacts are preserved)."

• [logic-error] docs/Plugin-Development-CLI.md:336 — The watch mode bullet says "Listens to container lifecycle events (die/start) rather than polling raw subprocesses." Two inaccuracies: (1) The code never listens for start events — it listens for died/die (installer completion) and cleanup/die (container teardown between cycles). (2) HTTP polling via waitForRhdhReady is the core readiness mechanism after every update cycle; the phrase "rather than polling" is false.
  Remediation: Revise to: "Listens to container lifecycle events (died/die for installer completion, cleanup/die for container teardown) with HTTP readiness polling for RHDH service availability."

Low

• [logic-error] docs/Plugin-Development-CLI.md:289 — The base stop table description says "Stop and remove RHDH Local runtime containers." Without --clean, the code runs compose stop (via composeArgs('stop')), which halts containers but does not remove them. Only --clean (via compose down) removes containers.
  Remediation: Change to "Stop RHDH Local runtime containers (use --clean to also remove containers and networks)."

• [incorrect-doc] docs/Plugin-Development-CLI.md:151 — The static compatibility matrix table lists only 5 RHDH→Backstage version pairs, but RHDH_COMPATIBILITY_MATRIX in src/lib/rhdhVersion.ts (lines 28–39) contains 7 versioned entries. Missing: 1.7.0 → Backstage 1.39.1 and 1.6.0 → Backstage 1.36.1. The doc explicitly calls this the "Fallback table embedded in the CLI," making the omission misleading.
  Remediation: Add the missing entries: 1.7.0 / 1.7 → Backstage 1.39.1 and 1.6.0 / 1.6 → Backstage 1.36.1.

• [incorrect-doc] docs/Plugin-Development-CLI.md:239 — The Lockfile Synchronization section says the CLI "detects whether your project uses Yarn (yarn.lock) or npm (package-lock.json)." The detectPackageManager function only checks for yarn.lock; it never inspects package-lock.json. If no yarn.lock is found, it defaults to npm unconditionally.
  Remediation: Clarify: "detects Yarn (yarn.lock) presence; defaults to npm when no yarn.lock is found."

• [incomplete-doc] docs/Plugin-Development-CLI.md:79 — The plugin new Syntax & Options section lists 6 flags but omits --name <plugin-name>, which is registered in src/commands/index.ts (line 178) as an alternative to the positional argument. README.md documents this option at line 82. The comprehensive guide should be consistent.
  Remediation: Add --name <plugin-name> to the Options list, describing it as an alternative to the positional <name> argument.

• [incorrect-doc] docs/Plugin-Development-CLI.md:83 — The --rhdh-version option description hardcodes "(defaults to latest supported GA release (2.1.0))" at lines 83 and 141. Currently accurate, but will silently become stale when the next RHDH release is added to the static compatibility matrix.
  Remediation: Replace with: "Defaults to the latest supported GA release (see RHDH_COMPATIBILITY_MATRIX in src/lib/rhdhVersion.ts)."

---

Labels: PR adds comprehensive documentation for CLI plugin commands

---

Next steps:

• /fs-fix — agent addresses review findings automatically
• /fs-fix <your instruction> — agent fixes with your specific guidance
• Push commits directly — review re-runs automatically on push
• /fs-fix-stop — disable automatic fix runs for this PR

[gashcrumb]

/fs-review

[fullsend-ai-review]

🤖 Finished Review · ✅ Success · Started 6:48 PM UTC · Completed 7:02 PM UTC

Commit: 78caf1e · View workflow run →

Runtime: claude · Model: sonnet → claude-sonnet-4-6 · Effort: high · Cost: $3.22

[fullsend-ai-review]

See the review comment for full details.

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud