feat: render PI diagram by vobu · Pull Request #60 · camunda/c8ctl

vobu · 2026-02-18T13:16:54Z

No description provided.

Add --diagram flag to 'get process-instance' command that generates a self-contained HTML file rendering the BPMN diagram with highlighted completed, active, and incident elements plus taken sequence flows. Uses bpmn-js from CDN for client-side rendering, following the same approach as Camunda Process Test coverage reports. Opens the generated HTML file in the default browser automatically. Usage: c8ctl get pi <key> --diagram [--output path.html]

Replace HTML output with PNG rendering using puppeteer-core and system-installed Chrome/Chromium. The diagram is rendered headlessly via bpmn-js, then screenshotted to PNG at 2x resolution. Requires Chrome or Chromium installed on the system. Falls back to a clear error message with download link if no browser is found.

Auto-detect terminals supporting inline images (iTerm2, kitty, WezTerm, VS Code, mintty, Konsole) and print the PNG directly to the console using the iTerm2 Inline Images Protocol. Falls back to saving a temp file and opening with the system viewer when the terminal doesn't support inline images. Explicit --output always saves to the given path.

Remove terminal auto-detection and file-open fallback. The diagram is always printed inline to the terminal via the iTerm2 Inline Images Protocol. Use --output to save the PNG to a file instead.

Copilot

Pull request overview

This pull request adds a new feature to render BPMN diagrams for process instances as PNG images with execution state highlighting. The feature integrates Puppeteer with system-installed Chrome/Chromium to render diagrams using bpmn-js, showing completed elements, active elements, incidents, and taken sequence flows with color-coded visualization.

Changes:

Adds --diagram flag and --output option to c8ctl get pi command for rendering process instance diagrams
Implements diagram generation using Puppeteer, headless Chrome, and bpmn-js from CDN
Updates help text, shell completions (bash, zsh, fish), and unit tests to reflect the new feature
Adds puppeteer-core dependency to package.json

Reviewed changes

Copilot reviewed 6 out of 7 changed files in this pull request and generated 9 comments.

Show a summary per file

File	Description
src/commands/diagram.ts	New module implementing process instance diagram rendering with Puppeteer and bpmn-js
src/index.ts	Adds --diagram and --output flag handling in the get pi command flow
src/commands/help.ts	Updates help text with --diagram and --output flag documentation and examples
src/commands/completion.ts	Adds --diagram and --output flags to bash, zsh, and fish shell completion scripts
tests/unit/help.test.ts	Adds test assertions for --diagram flag presence in help output
package.json	Adds puppeteer-core ^24.37.4 dependency
package-lock.json	Lockfile updates for puppeteer-core and transitive dependencies

src/index.ts

src/commands/diagram.ts

src/commands/completion.ts

src/commands/help.ts

src/commands/completion.ts

src/commands/diagram.ts

Copilot · 2026-02-18T13:47:41Z

@vobu I've opened a new pull request, #61, to work on those changes. Once the pull request is ready, I'll request review from you.

Copilot · 2026-02-18T13:47:55Z

@vobu I've opened a new pull request, #62, to work on those changes. Once the pull request is ready, I'll request review from you.

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Copilot

Pull request overview

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

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Copilot · 2026-02-18T13:59:46Z

@vobu I've opened a new pull request, #63, to work on those changes. Once the pull request is ready, I'll request review from you.

Copilot

Pull request overview

Copilot reviewed 6 out of 7 changed files in this pull request and generated 6 comments.

src/commands/diagram.ts

Copilot · 2026-02-18T14:02:30Z

src/commands/diagram.ts

+        window.__diagramRendered = true;
+      } catch (err) {
+        console.error('Failed to render BPMN diagram:', err);
+        window.__diagramRendered = true;
+      }


The embedded renderer sets window.__diagramRendered = true even when rendering fails (catch block), so Puppeteer will still take a screenshot (often blank) and the CLI will report success. Please propagate render failures back to Node (e.g., store an error message in window.__diagramError and have waitForFunction/assertions fail when it's set, and/or fail if no SVG is present).

@copilot open a new pull request to apply changes based on this feedback

Copilot · 2026-02-18T14:02:30Z

src/commands/diagram.ts

+export async function getProcessInstanceDiagram(key: string, options: {
+  profile?: string;
+  output?: string;
+}): Promise<void> {
+  const logger = getLogger();
+  const client = createClient(options.profile);
+  const consistencyOptions = { consistency: { waitUpToMs: 0 } };


No tests currently cover the new diagram functionality (routing via "get pi --diagram" and the diagram generation/output behavior). Per project guidelines, please add at least a minimal test (unit and/or integration) that validates the new flag behavior and expected outputs/failures.

src/commands/diagram.ts

src/index.ts

* Initial plan * docs: add diagram flag and output option examples to README and EXAMPLES Co-authored-by: vobu <6573426+vobu@users.noreply.github.com> --------- Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com> Co-authored-by: vobu <6573426+vobu@users.noreply.github.com>

* Initial plan * docs: add diagram flag examples to EXAMPLES.md Co-authored-by: vobu <6573426+vobu@users.noreply.github.com> --------- Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com> Co-authored-by: vobu <6573426+vobu@users.noreply.github.com>

* Initial plan * test: add integration tests for diagram feature Co-authored-by: vobu <6573426+vobu@users.noreply.github.com> --------- Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com> Co-authored-by: vobu <6573426+vobu@users.noreply.github.com>

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Copilot · 2026-02-18T14:12:33Z

@vobu I've opened a new pull request, #69, to work on those changes. Once the pull request is ready, I'll request review from you.

Copilot · 2026-02-18T14:12:42Z

@vobu I've opened a new pull request, #70, to work on those changes. Once the pull request is ready, I'll request review from you.

vobu · 2026-02-18T14:15:33Z

@copilot do some investigation as to why displaying/rendering the image works in iTerm2, but not in Ghostty - both should support the Kitty graphics protocol, so the png should always display. Find a way to assure correct implementation of displaying/outputting the graphic here.

Copilot · 2026-02-18T14:15:46Z

@vobu I've opened a new pull request, #71, to work on those changes. Once the pull request is ready, I'll request review from you.

* Initial plan * feat: bundle bpmn-js assets locally instead of using CDN - Add bpmn-js@18 as a dependency - Update build script to copy bpmn-js assets to dist/assets/bpmn-js/ - Update diagram.ts to use file:// URLs for bundled assets - Removes hard internet dependency for diagram rendering - Enables diagram rendering in air-gapped/proxied environments Co-authored-by: vobu <6573426+vobu@users.noreply.github.com> * chore: update package-lock.json after adding bpmn-js Co-authored-by: vobu <6573426+vobu@users.noreply.github.com> --------- Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com> Co-authored-by: vobu <6573426+vobu@users.noreply.github.com>

* Initial plan * test: add assertion for --output flag in get help test Co-authored-by: vobu <6573426+vobu@users.noreply.github.com> --------- Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com> Co-authored-by: vobu <6573426+vobu@users.noreply.github.com>

… diagrams (#68) * Initial plan * fix: ensure parent directory exists when saving diagram with --output Co-authored-by: vobu <6573426+vobu@users.noreply.github.com> --------- Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com> Co-authored-by: vobu <6573426+vobu@users.noreply.github.com>

* Initial plan * test: add assertion for --output flag in help tests Add assertion to verify --output flag appears in help text alongside --diagram flag, as both flags work together for diagram rendering. Co-authored-by: vobu <6573426+vobu@users.noreply.github.com> --------- Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com> Co-authored-by: vobu <6573426+vobu@users.noreply.github.com>

* Initial plan * fix: use parsed values for --variables flag instead of process.argv Co-authored-by: vobu <6573426+vobu@users.noreply.github.com> * docs: finalize PR addressing parseArgs feedback Co-authored-by: vobu <6573426+vobu@users.noreply.github.com> --------- Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com> Co-authored-by: vobu <6573426+vobu@users.noreply.github.com>

Copilot

Pull request overview

Copilot reviewed 9 out of 10 changed files in this pull request and generated 6 comments.

Copilot · 2026-02-18T14:36:55Z

src/commands/diagram.ts

+  process.stdout.write(`\x1b]1337;File=${args}:${base64}\x07\n`);
+}
+


The file:// URLs are constructed via string concatenation and simple backslash replacement. This will break for paths containing spaces or other characters needing URL-encoding. Prefer pathToFileURL(cssPath).href / pathToFileURL(jsPath).href (from node:url) to generate valid file URLs cross-platform.

Copilot · 2026-02-18T14:36:55Z

src/commands/diagram.ts

+
+    // 8. Output: save to file if --output, otherwise print inline
+    if (options.output) {


When --output points to a path in a non-existent directory, writeFileSync will throw and the user only gets the generic “Failed to generate diagram…” wrapper. Create the parent directory first (recursive) before writing (similar to how src/plugin-registry.ts ensures the parent dir exists before writeFileSync).

Copilot · 2026-02-18T14:36:55Z

tests/integration/process-instances.test.ts

+
+    try {
+      const output = execSync(
+        `node src/index.ts get pi --key ${instanceKey} --diagram --output ${outputPath}`,


These new integration tests invoke get pi using --key, but the CLI expects the process instance key as a positional argument (c8ctl get pi <key>). With --key, args[0] will be empty and the command will exit before rendering. Update the exec invocations to pass the key positionally (and keep flags after it).

Suggested change

`node src/index.ts get pi --key ${instanceKey} --diagram --output ${outputPath}`,

`node src/index.ts get pi ${instanceKey} --diagram --output ${outputPath}`,

Copilot · 2026-02-18T14:36:56Z

tests/integration/process-instances.test.ts

+    try {
+      const output = execSync(
+        `node src/index.ts get pi --key ${instanceKey} --diagram --output ${outputPath}`,
+        { encoding: 'utf8', cwd: process.cwd(), stdio: 'pipe' }
+      );


This “save PNG to file” test will hard-fail on systems/CI where Chrome/Chromium isn’t installed. The next test already treats the missing-Chrome error as a skip; apply the same handling here (or skip early) so the integration suite is stable across environments.

src/commands/diagram.ts

Copilot · 2026-02-18T14:36:56Z

src/commands/diagram.ts

+        diagramData.activeElements.forEach(function(elementId) {
+          canvas.addMarker(elementId, 'active-element');
+        });
+
+        diagramData.incidentElements.forEach(function(elementId) {


The HTML renderer sets window.__diagramRendered = true even when rendering fails, and the Node side only waits for that flag. This means missing assets / importXML errors will still be treated as success and you’ll write a PNG without warning. Capture the render error (e.g., window.__diagramError) and have renderDiagramToPng() fail when an error was reported, so users get an actionable error instead of a blank image.

…ring (#71) * Initial plan * feat: add Kitty Graphics Protocol support for Ghostty and other terminals Co-authored-by: vobu <6573426+vobu@users.noreply.github.com> * feat: add Sixel graphics protocol support and regenerate package-lock with Node 22 Co-authored-by: vobu <6573426+vobu@users.noreply.github.com> --------- Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com> Co-authored-by: vobu <6573426+vobu@users.noreply.github.com>

Copilot

Pull request overview

Copilot reviewed 9 out of 10 changed files in this pull request and generated 2 comments.

src/commands/diagram.ts

Copilot · 2026-02-18T15:01:36Z

tests/integration/process-instances.test.ts

+    } catch (error: any) {
+      // On systems without Chrome/Chromium, this test may fail
+      // Verify it fails with a helpful error message
+      if (error.stderr && error.stderr.includes('No Chrome or Chromium browser found')) {


The test silently passes when Chrome/Chromium is not installed, which means the actual diagram rendering functionality is not being tested in CI environments without a browser. Consider using a mock or ensuring the test environment has Chrome installed, or mark this as a skipped test rather than passing.

@copilot open a new pull request to apply changes based on this feedback

Copilot · 2026-02-23T12:46:59Z

@vobu I've opened a new pull request, #80, to work on those changes. Once the pull request is ready, I'll request review from you.

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Copilot · 2026-02-23T12:47:40Z

@vobu I've opened a new pull request, #81, to work on those changes. Once the pull request is ready, I'll request review from you.

vobu · 2026-02-23T12:49:12Z

@copilot the diagram creation doesn't work at all. fix this. then refactor so that this feature can become a c8ctl plugin rather than built into c8ctl directly. Move the code into /default-plugins for now and prepare that it can be carved out into a standalone repository.

Copilot · 2026-02-23T12:49:22Z

@vobu I've opened a new pull request, #82, to work on those changes. Once the pull request is ready, I'll request review from you.

Copilot

Pull request overview

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

vobu added 4 commits February 18, 2026 13:42

refactor: always print diagram inline, use --output to save

7dafbc3

Remove terminal auto-detection and file-open fallback. The diagram is always printed inline to the terminal via the iTerm2 Inline Images Protocol. Use --output to save the PNG to a file instead.

Copilot AI review requested due to automatic review settings February 18, 2026 13:16

Copilot started reviewing on behalf of vobu February 18, 2026 13:17 View session

Copilot AI reviewed Feb 18, 2026

View reviewed changes

Copilot AI mentioned this pull request Feb 18, 2026

docs: add diagram flag and output option to README and EXAMPLES #61

Merged

Copilot AI mentioned this pull request Feb 18, 2026

docs: add diagram flag examples to EXAMPLES.md #62

Merged

fix: update src/commands/diagram.ts

5f592e3

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Copilot AI review requested due to automatic review settings February 18, 2026 13:49

Copilot started reviewing on behalf of vobu February 18, 2026 13:50 View session

Copilot AI reviewed Feb 18, 2026

View reviewed changes

docs: update src/commands/completion.ts

c5a7e6e

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Copilot AI review requested due to automatic review settings February 18, 2026 13:57

vobu and others added 2 commits February 18, 2026 14:58

docs: update src/commands/help.ts

c277156

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

docs: update src/commands/completion.ts

685667e

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Copilot started reviewing on behalf of vobu February 18, 2026 13:58 View session

Copilot AI mentioned this pull request Feb 18, 2026

Add integration test coverage for diagram feature #63

Merged

Copilot AI reviewed Feb 18, 2026

View reviewed changes

Copilot AI and others added 2 commits February 18, 2026 15:04

Copilot AI review requested due to automatic review settings February 18, 2026 14:05

Copilot started reviewing on behalf of vobu February 18, 2026 14:06 View session

Copilot AI and others added 2 commits February 18, 2026 15:06

fix: update src/commands/diagram.ts

e5b7a51

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Copilot AI mentioned this pull request Feb 18, 2026

Bundle bpmn-js assets locally instead of loading from CDN #64

Merged

Copilot AI mentioned this pull request Feb 18, 2026

Fix parseArgs flag handling for --variables option #69

Merged

Copilot AI mentioned this pull request Feb 18, 2026

test: add missing --output flag assertion in help tests #70

Merged

Copilot AI mentioned this pull request Feb 18, 2026

feat: add Kitty Graphics Protocol and Sixel support for diagram rendering #71

Merged

Copilot AI and others added 2 commits February 18, 2026 15:18

Copilot AI review requested due to automatic review settings February 18, 2026 14:19

Copilot started reviewing on behalf of vobu February 18, 2026 14:20 View session

Copilot AI and others added 3 commits February 18, 2026 15:21

Copilot AI reviewed Feb 18, 2026

View reviewed changes

Copilot AI and others added 2 commits February 18, 2026 15:50

Merge branch 'main' into feat/process-instance-diagram

2af6840

Copilot AI review requested due to automatic review settings February 18, 2026 14:54

Copilot AI reviewed Feb 18, 2026

View reviewed changes

Copilot AI mentioned this pull request Feb 23, 2026

fix: use t.skip() instead of assert.ok(true) when Chrome is unavailable in diagram test #80

Draft

chore: update src/commands/diagram.ts

20530a0

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Copilot AI review requested due to automatic review settings February 23, 2026 12:47

Copilot started reviewing on behalf of vobu February 23, 2026 12:47 View session

Copilot AI mentioned this pull request Feb 23, 2026

fix: propagate BPMN render failures from browser to Node in diagram rendering #81

Draft

Copilot AI mentioned this pull request Feb 23, 2026

feat: refactor diagram rendering into default plugin, fix broken dev-mode asset resolution #82

Draft

Copilot AI reviewed Feb 23, 2026

View reviewed changes

		process.stdout.write(`\x1b]1337;File=${args}:${base64}\x07\n`);
		}


		// 8. Output: save to file if --output, otherwise print inline
		if (options.output) {

	`node src/index.ts get pi --key ${instanceKey} --diagram --output ${outputPath}`,
	`node src/index.ts get pi ${instanceKey} --diagram --output ${outputPath}`,

Comments

Conversation

vobu commented Feb 18, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI commented Feb 18, 2026

Uh oh!

Copilot AI commented Feb 18, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Copilot AI commented Feb 18, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Copilot AI Feb 18, 2026

Choose a reason for hiding this comment

Uh oh!

vobu Feb 23, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 18, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Copilot AI commented Feb 18, 2026

Uh oh!

Copilot AI commented Feb 18, 2026

Uh oh!

vobu commented Feb 18, 2026

Uh oh!

Copilot AI commented Feb 18, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Copilot AI Feb 18, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 18, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 18, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 18, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Copilot AI Feb 18, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Copilot AI Feb 18, 2026

Choose a reason for hiding this comment