feat: collect 'em low-hanging-fruits

[vobu]

(ping to https://github.com/camunda/product-hub/issues/2638 for tracability)

Summary

This PR bundles several low-hanging but high-impact CLI improvements across profiles, search, and plugins.

It improves discoverability (help + completion + docs), fixes a profile auth edge case for imported Modeler connections, adds source-aware plugin upgrade/downgrade behavior, and hardens flaky integration paths in search/plugin lifecycle tests.

What changed

Profiles and help UX

• Added dedicated c8 help profiles output (including profile alias handling) in src/commands/help.ts.
• Expanded command-help discoverability in shell completion suggestions in src/commands/completion.ts.
• Updated profile/help documentation in README.md and EXAMPLES.md.
• Added/updated help test coverage in tests/unit/help.test.ts.

Profile/auth fix

• Fixed cloud Modeler mapping so audience stays optional unless explicitly configured (instead of being forced) in src/config.ts.
• Added regression coverage in tests/unit/config.test.ts.

Search behavior and test stability

• Improved process-definition search determinism (sorting by version/key) and strengthened case-insensitive behavior/pagination in src/commands/search.ts.
• Stabilized integration polling/filter behavior in tests/integration/search.test.ts to avoid eventual-consistency flakiness.

Plugin management improvements

• Implemented source-aware plugin upgrade/downgrade behavior with clearer actionable hints in src/commands/plugins.ts.
• Enhanced plugin listing/version visibility and added lifecycle/version test coverage in:
  • tests/integration/plugin-lifecycle.test.ts
  • tests/unit/plugins-version.test.ts
• Added plugin-help documentation in PLUGIN-HELP.md.

Why

• Reduce friction and confusion around profile setup and help discoverability.
• Eliminate profile reuse/auth regressions when using Camunda Modeler connections.
• Improve determinism and reliability in search output and integration tests.
• Make plugin operations safer and clearer across npm/git/file source types.

Diff

• Branch diff summary: 13 files changed, 748 insertions, 38 deletions.

[Copilot]

Pull request overview

This PR bundles several CLI usability and reliability improvements across profiles/help UX, search determinism, and plugin management, plus accompanying documentation and test updates.

Changes:

• Added dedicated help output for profiles and plugin(s), and expanded shell completion coverage accordingly.
• Fixed Modeler Cloud connection mapping so OAuth audience remains optional unless explicitly provided.
• Improved search determinism (process definition sorting) and case-insensitive variable search pagination; stabilized related integration tests.
• Enhanced plugin listing with version visibility and implemented source-aware upgrade/downgrade behavior, including new unit/integration coverage and docs.

Reviewed changes

Copilot reviewed 13 out of 13 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
tests/unit/plugins-version.test.ts	Adds unit coverage for plugin version helper functions.
tests/unit/help.test.ts	Extends help tests to cover profiles and plugin(s) detailed help.
tests/unit/config.test.ts	Adds regression tests for Cloud connection audience handling.
tests/integration/search.test.ts	Stabilizes search integration tests using instance-based key extraction and job filtering.
tests/integration/plugin-lifecycle.test.ts	Adds version visibility assertion and upgrade/downgrade behavior tests for file-sourced plugins.
src/config.ts	Updates Cloud Modeler connection mapping to keep audience optional and allow custom OAuth URL.
src/commands/search.ts	Adds deterministic sorting for process definitions and paginates case-insensitive variable searches.
src/commands/plugins.ts	Adds version helpers, shows versions in list plugins, and makes upgrade/downgrade source-aware.
src/commands/help.ts	Adds help profiles and help plugin(s) detailed help output and wiring.
src/commands/completion.ts	Expands completion suggestions to include profiles/profile/plugin/plugins help topics.
README.md	Documents new help entrypoints and plugin version/source-aware upgrade/downgrade behavior.
PLUGIN-HELP.md	Documents source-aware upgrade/downgrade semantics by source type.
EXAMPLES.md	Adds examples for profile help and source-aware plugin upgrade/downgrade; updates plugin list example with Version column.

[Copilot]

Pull request overview

Copilot reviewed 13 out of 13 changed files in this pull request and generated no new comments.

[github-actions]

This has been released in 2.1.0-alpha.4.

[github-actions]

This has been released in 2.1.0.