feat: add arazzo explore to interactively browse arazzo workflows

Merged
TR
4d ago
+2005-1

Stacked on #317 (which is stacked on #316, #315, #306 and #305). Review those first; this PR's diff is against feat/arazzo-bootstrap.

Why

openapi spec explore gives OpenAPI users a quick way to browse a spec in the terminal, but there was nothing equivalent for Arazzo. Reading an Arazzo document's flow means jumping between steps, workflow level actions and components to work out which parameters and actions actually apply to a step.

What changed

openapi arazzo explore <file> opens an interactive terminal UI (stdin supported) listing each workflow with its steps underneath.

  • Steps have a badge for what they target: OP (operationId), PATH (operationPath), FLOW (workflowId), and SEND/RECV/CHAN for AsyncAPI channelPath steps.
  • Expanding a workflow shows its summary, description, dependsOn, inputs (types and which are required), parameters, success and failure actions and outputs.
  • Expanding a step shows its target, correlationId and timeout, dependsOn, parameters, request body (payload and replacements), success criteria (with type, version and context), success and failure actions, and outputs (including selector outputs).
  • Parameters and actions that reference components are shown resolved, noting the component. A step's actions include the workflow level actions it inherits, marked (from workflow), unless the step overrides them by name.
  • Keys match spec explore (j/k, gg/G, Ctrl-U/Ctrl-D, Enter/Space, ?, q), plus [/] to jump between workflows and e/E to expand or collapse all details.
  • Validation errors are listed before the explorer starts (first five, then a count), but don't stop the document being explored.

The code is in cmd/openapi/internal/arazzoexplore: Collect flattens a document into rows with plain-text details, and Model is the bubbletea UI. The command is cmd/openapi/commands/arazzo/explore.go. Docs are in the Arazzo CLI README (with real rendered output) and the root README.

Review notes

  • This is a separate model rather than a generalisation of cmd/openapi/internal/explore/tui. That package is built around OpenAPI operations and is also used by spec snip's selection mode, so generalising it would mean changing a working, tested UI for a second consumer. The new package reuses its exported styles, so both explorers look the same, and keeps the same key bindings. The scrolling logic is small and covered by tests here. If we want to share it, I'd do that as a follow-up.
  • Nothing in the root module changed, so cmd/openapi doesn't need repinning for this PR.
  • Scroll indicators only appear when there are at least three lines for content, so very short terminals still show the cursor row. Long lines are truncated to the terminal width so the line accounting stays correct.
  • The explorer doesn't load source descriptions, so steps show their operationId rather than the operation's method and path. That would be a good follow-up, reusing the source loading from validate.
  • Tests cover Collect against a document using every detail type (component references, overrides, inheritance, selector outputs, AsyncAPI steps, nested workflows, untargeted steps), plus incomplete models built in code. They also cover every key binding, scrolling invariants at several terminal heights, scroll indicators, the help modal, rendered rows and footer, and the CLI loading paths (file, stdin, validation warnings, errors).
  • Coverage: 99.2% of arazzoexplore. In the CLI, the only untested lines are runExplore's tea.Program wiring, which needs a real terminal. test-cli checks --help for the same reason.

Summary by cubic

Adds openapi arazzo explore, an interactive terminal UI for browsing Arazzo workflows, the counterpart to openapi spec explore. It lists workflows with their steps, and expanding rows shows details like inputs, parameters, actions, criteria, and outputs, with components references resolved.

What's included

  • Steps have badges for operationId, operationPath, workflowId, and AsyncAPI channelPath steps.
  • Key bindings match spec explore (j/k, gg/G, Ctrl-U/Ctrl-D, Enter/Space, ?, q) plus [/] to jump between workflows and e/E to expand/collapse all.
  • Validation errors are counted and the first five listed on stderr, but don't stop the document from being explored.
  • Reads from a file or stdin; stdin prints a note that the TUI needs /dev/tty for keyboard input.
  • Implemented in a new arazzoexplore package that reuses the existing explorer TUI's styles; spec explore is unchanged.
  • Steps show their operationId rather than the operation's method and path; loading source descriptions is a follow-up.