feat: add arazzo explore to interactively browse arazzo workflows
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), andSEND/RECV/CHANfor AsyncAPIchannelPathsteps. - 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,
correlationIdandtimeout,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
componentsare 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 ande/Eto 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 byspec 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/openapidoesn'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
operationIdrather than the operation's method and path. That would be a good follow-up, reusing the source loading fromvalidate. - Tests cover
Collectagainst 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 arerunExplore'stea.Programwiring, which needs a real terminal.test-clichecks--helpfor 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 AsyncAPIchannelPathsteps. - Key bindings match
spec explore(j/k,gg/G,Ctrl-U/Ctrl-D,Enter/Space,?,q) plus[/]to jump between workflows ande/Eto 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/ttyfor keyboard input. - Implemented in a new
arazzoexplorepackage that reuses the existing explorer TUI's styles;spec exploreis unchanged. - Steps show their
operationIdrather than the operation's method and path; loading source descriptions is a follow-up.