New command: interactive HTTP request explorer (no assertions)

[snytkine]

Summary

Add a new Spring Shell command (e.g. explore-suite / es-ui) that loads a test-suite YAML file and presents an interactive terminal UI for browsing and executing individual HTTP requests — without running any assertions. This is a developer-facing tool for exploring and debugging APIs while iterating on request payloads.

Motivation

run-suite is designed for automated test execution with pass/fail assertions. Users also need a way to fire individual requests ad-hoc, inspect raw responses, tweak payloads, and re-send — all without leaving the terminal. Think of it as an interactive HTTP client driven by the existing test-suite YAML format.

---

Functional Requirements

Command entry point

• New @Command (e.g. explore-suite, alias es) that accepts --suite=<path> and optional key=value CLI variables (same as run-suite)
• Only available in interactive (TTY) mode; prints an error and exits if not on a TTY

Test list view

• On startup, load the test-suite YAML (full two-pass Thymeleaf processing via TestSuiteLoader)
• Display a scrollable list of all test case names
• Up / Down arrow keys navigate the list; selected item is highlighted
• Status indicator per item:
  • Idle (default)
  • Spinner — request in flight (same spinner glyph/animation used in the existing run-suite TUI)
  • Last HTTP status code + response time once a response has been received (e.g. 200 142ms)

Executing a request

• Enter on a highlighted test fires the HTTP request for that test case (using the existing PureJavaTestEngine HTTP client / RestClient builder, skipping assertion evaluation)
• While the request is in flight the list row shows a spinner; the UI remains responsive (other rows still navigable)
• Multiple in-flight requests at the same time should be supported if the user presses Enter on multiple rows quickly

Response view

After a response arrives, display it in the terminal below (or beside) the list — TBD whether this is a split-pane layout or a modal overlay (see open questions):

Section	Content
Status	HTTP status code + reason phrase
Time	Total response time in ms
Headers	Key/value table (response headers)
Body	Raw body; if Content-Type is application/json → pretty-printed JSON

Request detail view

• A keyboard shortcut (e.g. R or Tab) toggles a request detail panel showing:
  • HTTP method + full URL (after variable resolution)
  • Request headers
  • Request body (pretty-printed if JSON)
• TBD: modal overlay vs. split-pane — investigate Spring Shell TUI modal support (see open questions)

Live file reload

• Each time the user triggers a request (presses Enter), the suite YAML and all referenced body/schema files are re-read from disk before building the request
• This allows the user to edit the YAML or JSON body files in a separate editor and immediately re-send with the updated payload from the same interactive window — no restart required
• Variable resolution (Thymeleaf, CLI vars, .env) is re-run on every execution so changes to those files are also picked up

---

Non-functional Requirements

• Thread-safety: HTTP calls must be dispatched off the main TUI thread so the UI stays responsive; use the same event-queue pattern as TerminalUiController / TestProgressEvent
• GraalVM native image compatible (no runtime reflection without AOT hints)
• Follows existing code conventions: Google Java Format, Apache 2.0 header, JavaDoc on every class and public method

---

Open Questions

1. Response / request display layout — modal overlay vs. persistent split-pane. Investigate whether Spring Shell's TUI component model supports modals; if not, a split-pane (list top, detail bottom) is the fallback.
2. Multiple simultaneous responses — if two requests are in flight and both return, which response is shown? Likely the most recently selected row drives the detail pane.
3. Error display — network errors, connection timeouts, SSL failures: how to surface these in the list row and detail pane.
4. Scrollable body — large JSON responses may exceed terminal height; need a scrollable body area.
5. Command name / alias — avoid collision with the new export-schema alias es; pick a non-conflicting name.

---

Suggested Implementation Approach

New classes

Class	Role
ExploreSuiteCommand	@Command entry point; validates TTY, loads suite, starts TUI
ExploreUiController	Owns the TUI event loop and Spring Shell ViewComponent; analogous to TerminalUiController
ExploreProgressEvent	Sealed event hierarchy: RequestStarted, ResponseReceived, RequestFailed
HttpRequestExecutor (or reuse engine)	Fires a single request without assertion evaluation; returns a raw response record
Response/request detail renderer	Renders status, headers, body (pretty JSON), response time

Reuse opportunities

• TestSuiteLoader.load() — full YAML + Thymeleaf processing, called on every request execution for live reload
• DotEnvLoader.loadDotEnv() — .env resolution
• PureJavaTestEngine HTTP client / RestClient builder — or extract the request-building logic into a shared utility
• Glyphs — spinner characters
• TtyDetector — color support, terminal width
• TerminalUiController event-queue pattern — LinkedBlockingQueue<ExploreProgressEvent>

---

Labels

enhancement, tui, new-command