CAMEL-21975: Add route-diagram command to display Camel route diagrams in terminal

[gnodet]

CAMEL-21975

Summary

Adds a new camel cmd route-diagram command that renders visual diagrams of Camel routes directly in the terminal using inline image protocols (Kitty, iTerm2, Sixel), with a text-based tree fallback for unsupported terminals.

• Connects to a running Camel integration via PID and fetches route structure
• Renders a 2D diagram with colored nodes, arrows, merge lines, and branching layout
• Supports --output <file.png> to save the diagram as a PNG file
• Supports --filter to narrow by route ID or source filename
• Supports --theme for color customization (presets: dark, light, transparent)
• Falls back to a text-based ASCII tree diagram when no graphics protocol is available

Architecture

• RouteDiagramLayoutEngine — tree building, subtree width computation, and coordinate assignment
• RouteDiagramRenderer — Java AWT rendering (nodes, arrows, merge lines) and text fallback
• CamelRouteDiagramAction — CLI entry point, JSON parsing, terminal display via JLine TerminalGraphics

Color Palette

Colors are based on the GitHub Primer design system, following dark mode best practices:

• No pure black/white backgrounds (dark: #0d1117, light: #f6f8fa)
• Desaturated fills to avoid optical vibrations
• No red/orange for normal processing nodes
• Semantic color mapping: green=source, blue=destination, purple=patterns, gold=decisions, teal=transforms, pink=processing

Customization

Colors are fully customizable via --theme (or DIAGRAM_COLORS env var):

# Use a preset
camel cmd route-diagram --theme dark
camel cmd route-diagram --theme light
camel cmd route-diagram --theme transparent

# Custom hex colors
camel cmd route-diagram --theme "bg=#1a1a2e:from=#16a085:to=#2980b9:processor=#8e44ad"

# ANSI color names (via JLine)
camel cmd route-diagram --theme "from=seagreen:to=steelblue:processor=mediumpurple"

# Mix presets with overrides
camel cmd route-diagram --theme "light:from=#00695c:to=#01579b"

# Environment variable
export DIAGRAM_COLORS="dark:processor=#7b68ee"

Available color keys: bg, text, arrow, label, from, to, eip, choice, default, transform, processor

Test plan

• Unit tests for tree building (empty, single, sequential, branching, deeply nested, walk-up)
• Unit tests for layout engine (single route, branching, empty)
• Unit tests for color parsing (presets, custom hex, color names, invalid input, transparent)
• Unit tests for image rendering (opaque, transparent, max dimension guard)
• Unit tests for text diagram fallback (sequential, branching, empty)
• Unit tests for JSON route parsing (empty, with data)
• Manual test with running Camel integration in Kitty/iTerm2/VS Code terminals

[github-actions]

🌟 Thank you for your contribution to the Apache Camel project! 🌟
🤖 CI automation will test this PR automatically.

🐫 Apache Camel Committers, please review the following items:

• First-time contributors require MANUAL approval for the GitHub Actions to run
• You can use the command /component-test (camel-)component-name1 (camel-)component-name2.. to request a test from the test bot although they are normally detected and executed by CI.
• You can label PRs using skip-tests and test-dependents to fine-tune the checks executed by this PR.
• Build and test logs are available in the summary page. Only Apache Camel committers have access to the summary.

⚠️ Be careful when sharing logs. Review their contents before sharing them publicly.

[github-actions]

🧪 CI tested the following changed modules:

• docs
• dsl/camel-jbang/camel-jbang-core

⚠️ Some tests are disabled on GitHub Actions (@DisabledIfSystemProperty(named = "ci.env.name")) and require manual verification:

• dsl/camel-jbang/camel-jbang-core: 1 test(s) disabled on GitHub Actions

💡 Manual integration tests recommended:

You modified dsl/camel-jbang/camel-jbang-core. The related integration tests in dsl/camel-jbang/camel-jbang-it are excluded from CI. Consider running them manually:

mvn verify -f dsl/camel-jbang/camel-jbang-it -Djbang-it-test

All tested modules (6 modules)

• Camel :: JBang :: Core
• Camel :: JBang :: MCP
• Camel :: JBang :: Plugin :: Route Parser
• Camel :: JBang :: Plugin :: TUI
• Camel :: JBang :: Plugin :: Validate
• Camel :: Launcher :: Container

---

⚙️ View full build and test results

[davsclaus]

is there a design for the colors in the diagram. I dont think we should use red as it indicate an error or something wrong.

[gnodet]

is there a design for the colors in the diagram. I dont think we should use red as it indicate an error or something wrong.

I've updated the PR description to show the new palette and explain customisations. That definitely looks much better now :-). If you want adjustments or switching color/eip assignment, let me know.

[davsclaus]

awesome feature, thanks

[davsclaus]

I wonder if we in the tui, can have a 'd' short-cut in the routes tab, to show the diagram for the given route, and with scroll bars to make it possible to browse the entire route when its large.

[gnodet]

Great idea! Yes, this is definitely doable as a follow-up PR. The rendering infrastructure from this PR (layout engine + renderer) can be reused directly — we'd just need to wire a d key binding in the routes tab to render the diagram for the selected route and display it in a scrollable panel.

I'll open a follow-up JIRA ticket for this once this PR is merged.

Claude Code on behalf of Guillaume Nodet

[davsclaus]

LGTM

[davsclaus]

Falls back to a text-based ASCII tree diagram when no graphics protocol is available

Can we add an option (such as --ascii) so the end user can decide to use the ascii tree diagram.

[davsclaus]

Hey maybe we can just use the theme option, so you can do camel cmd route-diagram --theme ascii

[davsclaus]

@gnodet ^^^