feat: interactive force-directed HTML graph visualization

[nvandessel]

Summary

• Adds floop graph --format html that generates a self-contained HTML file with an interactive force-directed graph visualization, then opens it in the default browser
• Nodes are colored by behavior kind (Catppuccin Mocha palette), sized by PageRank + degree, with hover tooltips and click detail panels
• Uses force-graph v1.51.1 (MIT, ~177KB) embedded via //go:embed — works offline, no server needed
• Also updates MCP floop_graph handler to support html format

New CLI flags

floop graph --format html              # Generate HTML, open in browser
floop graph --format html -o graph.html  # Save to specific path
floop graph --format html --no-open    # Generate without opening browser

New files

• internal/visualization/assets/force-graph.min.js — Embedded JS library
• internal/visualization/templates/graph.html.tmpl — HTML template with CSS + visualization JS
• internal/visualization/embed.go — //go:embed directives
• internal/visualization/browser.go — Cross-platform OpenBrowser() (xdg-open/open/cmd)

Modified files

• internal/visualization/dot.go — FormatHTML, EnrichmentData, RenderEnrichedJSON(), RenderHTML(), collectEdges()
• cmd/floop/cmd_graph.go — HTML format case, --output/-o, --no-open flags, PageRank computation
• internal/mcp/handlers.go — HTML case in handleFloopGraph
• internal/mcp/schema.go — Updated format description

Test plan

• go test ./internal/visualization/... — 12 tests pass (enriched JSON, HTML rendering, browser smoke, edge collection)
• go test ./... — All 24 packages pass
• go build ./cmd/floop — Binary compiles with embedded assets
• floop graph --format html --no-open -o /tmp/test.html — 205KB self-contained HTML generated
• floop graph --format dot and --format json — Existing formats unchanged
• Manual: Open generated HTML in browser, verify force-directed layout, hover tooltips, click detail panel, zoom/pan

🤖 Generated with Claude Code

[greptile-apps]

Greptile Overview

Greptile Summary

This PR adds an offline, self-contained interactive HTML graph renderer (force-graph embedded via go:embed) and wires --format html into the floop graph CLI and the MCP floop_graph tool.

The visualization is generated from the existing behavior graph JSON, optionally enriched with PageRank scores for node sizing, rendered through an embedded HTML template + embedded JS asset, then either printed (dot/json) or written to disk (html) and optionally opened in a browser.

Confidence Score: 3/5

• This PR is close to merge-ready but has a few correctness/integration issues affecting HTML opening and MCP output lifecycle.
• Core rendering approach is straightforward and covered by tests, but the CLI constructs an invalid/non-portable file:// URL and the MCP handler writes temp files without cleanup while the schema docs don’t describe the html output shape, which can break clients or cause resource leaks.
• cmd/floop/cmd_graph.go, internal/mcp/handlers.go, internal/mcp/schema.go

Important Files Changed

Filename	Overview
cmd/floop/cmd_graph.go	Adds html graph output with optional write-to-file and browser open; current file URL construction uses "file://"+path which is invalid on Windows.
internal/mcp/handlers.go	Adds html format support to floop_graph by rendering HTML to a temp file; leaves temp files behind (no cleanup) and returns file path in Graph.
internal/mcp/schema.go	Updates format description to include html, but output schema still describes Graph as only DOT string or JSON object (html returns a file path string).
internal/visualization/assets/LICENSE-force-graph	Adds vendored force-graph license text for embedded JS asset.
internal/visualization/assets/force-graph.min.js	Adds embedded vendored force-graph minified JS library used for offline HTML rendering.
internal/visualization/browser.go	Adds cross-platform OpenBrowser helper using xdg-open/open/cmd start; correctness depends on callers passing a valid URL.
internal/visualization/browser_test.go	Adds compile/supported-platform smoke tests for OpenBrowser (does not actually open a browser).
internal/visualization/dot.go	Adds HTML rendering pipeline (RenderEnrichedJSON, RenderHTML) and shared collectEdges; enrichment logic relies on RenderJSON node slice type.
internal/visualization/dot_test.go	Adds tests for enriched JSON, HTML rendering, and edge collection; includes checks that may be brittle (size-based HTML assertion).
internal/visualization/embed.go	Embeds visualization assets and templates via //go:embed for offline HTML generation.
internal/visualization/templates/graph.html.tmpl	Adds self-contained HTML template with force-graph visualization, tooltip, and detail panel; uses innerHTML only with escaped content.

Sequence Diagram

sequenceDiagram
  participant User
  participant CLI as floop CLI
  participant GS as GraphStore
  participant Rank as ranking.ComputePageRank
  participant Viz as visualization.RenderHTML
  participant Assets as go:embed assets/templates
  participant FS as OS filesystem
  participant Browser as OpenBrowser
  participant MCP as MCP Server

  alt CLI: floop graph --format html
    User->>CLI: run graph command
    CLI->>GS: openStoreForGraph(root)
    CLI->>Rank: ComputePageRank(ctx, GS)
    CLI->>Viz: RenderHTML(ctx, GS, enrichment)
    Viz->>GS: QueryNodes / GetEdges
    Viz->>Assets: ReadFile(force-graph.min.js, graph.html.tmpl)
    Viz-->>CLI: htmlBytes
    CLI->>FS: WriteFile(outPath, htmlBytes)
    opt --no-open not set
      CLI->>Browser: OpenBrowser(file://...)
    end
  else MCP: floop_graph format=html
    User->>MCP: CallTool floop_graph
    MCP->>Viz: RenderHTML(ctx, store, enrichment)
    Viz->>Assets: ReadFile(force-graph.min.js, graph.html.tmpl)
    Viz-->>MCP: htmlBytes
    MCP->>FS: CreateTemp + Write(htmlBytes)
    MCP-->>User: Graph=tempFilePath
  end

Loading

[greptile-apps]

_{11 files reviewed, 3 comments}

_{Edit Code Review Agent Settings | Greptile}

[greptile-apps]

Additional Comments (1)

internal/mcp/schema.go
Schema mismatch for html

FloopGraphOutput.Graph is documented as "DOT string or JSON object", but the handler returns a temp file path string for format: "html". This makes the tool output misleading/incorrect for clients that rely on the schema description; update the schema docstring (and/or type shape) to include the html case (e.g., "DOT string, JSON object, or HTML file path").

[nvandessel]

@greptile review

[greptile-apps]

Greptile Overview

Greptile Summary

Adds a new HTML output path for the behavior graph: floop graph --format html now renders a self-contained, offline-capable force-directed visualization (force-graph embedded via go:embed) and optionally opens it in the default browser.

The visualization pipeline builds enriched node/edge JSON (including optional PageRank scores and canonical content for a detail panel), injects it into an embedded HTML template, and exposes the same html format through the MCP floop_graph tool.

Confidence Score: 3/5

• This PR is close to mergeable, but the HTML renderer currently introduces a concrete stored-XSS/script-injection issue.
• Core functionality (rendering + embedding assets + CLI/MCP wiring) is straightforward and covered by tests, but RenderHTML injects graph JSON into a <script> tag via template.JS, allowing </script> in stored behavior text to break out and execute attacker-controlled JS when the HTML is opened.
• internal/visualization/dot.go and internal/visualization/templates/graph.html.tmpl

Important Files Changed

Filename	Overview
cmd/floop/cmd_graph.go	Adds html graph output path/flags, renders embedded HTML via visualization.RenderHTML, and optionally opens browser.
internal/mcp/handlers.go	Extends floop_graph tool to support html format and returns rendered HTML plus node/edge counts.
internal/mcp/schema.go	Updates schema description to include html format for floop_graph.
internal/visualization/assets/LICENSE-force-graph	Adds embedded license file for force-graph dependency.
internal/visualization/assets/force-graph.min.js	Adds embedded force-graph minified JS asset used by HTML renderer.
internal/visualization/browser.go	Adds cross-platform OpenBrowser helper using xdg-open/open/cmd start; prior review noted file:// URL correctness concerns.
internal/visualization/browser_test.go	Adds compilation/supported-platform smoke tests for OpenBrowser.
internal/visualization/dot.go	Adds HTML rendering pipeline (enriched JSON + template + embedded JS) and CollectEdges; uses template.JS for GraphJSON which enables script-breakout XSS.
internal/visualization/dot_test.go	Adds tests for enriched JSON, HTML rendering, and CollectEdges; does not cover script-breakout escaping edge cases.
internal/visualization/embed.go	Adds go:embed directives for assets and templates.
internal/visualization/templates/graph.html.tmpl	Adds self-contained HTML template with force-graph visualization and detail panel; consumes raw injected JS/JSON from Go templates.

Sequence Diagram

sequenceDiagram
  participant User
  participant CLI as floop CLI
  participant Store as GraphStore
  participant Rank as ranking.ComputePageRank
  participant Viz as visualization.RenderHTML
  participant Embed as embed.FS assets/templates
  participant Browser as visualization.OpenBrowser

  User->>CLI: floop graph --format html [-o path] [--no-open]
  CLI->>Store: openStoreForGraph(root)
  CLI->>Rank: ComputePageRank(ctx, Store, config)
  Rank-->>CLI: map[behaviorID]score
  CLI->>Viz: RenderHTML(ctx, Store, enrichment)
  Viz->>Store: QueryNodes(kind=behavior)
  Viz->>Store: GetEdges(outbound, all)
  Viz->>Embed: ReadFile(assets/force-graph.min.js)
  Viz->>Embed: ReadFile(templates/graph.html.tmpl)
  Viz-->>CLI: HTML bytes (self-contained)
  CLI->>CLI: WriteFile(outPath, htmlBytes)
  alt no-open = false
    CLI->>Browser: OpenBrowser(outPath)
    Browser-->>CLI: cmd.Start()
  end

  Note over Viz,Embed: Template injects ForceGraphJS + GraphJSON into <script> tags

Loading

[greptile-apps]

_{11 files reviewed, 1 comment}

_{Edit Code Review Agent Settings | Greptile}

[greptile-apps]

Script-breakout XSS risk

RenderHTML injects graphJSON into a <script> block via template.JS(graphJSON). Since graphJSON includes stored behavior strings (e.g., canonical from the graph store), a value containing </script> will terminate the script tag and allow arbitrary HTML/JS injection when the generated HTML is opened. This is a real stored-XSS vector for anyone viewing the graph. Consider embedding JSON as escaped text (e.g., <script type="application/json"> + json.HTMLEscape) and then JSON.parse(...), or otherwise ensure </script> can’t appear in the injected script context.