feat: implement Wire runtime support with context-aware execution and enhanced error handling

[ziflex]

This pull request introduces comprehensive support for the Wire runtime in the Ferret CLI, enabling execution against a Universal API runtime via a local TCP endpoint. It adds new configuration flags, updates documentation, and includes extensive testing for Wire-specific behaviors and error handling. The PR also refactors diagnostics output handling and simplifies result writing for command execution. Below are the most important changes:

Wire Runtime Integration and Configuration:

• Adds support for the Wire runtime, including new CLI flags (--runtime, --runtime-endpoint, --runtime-connect-timeout) and environment variable overrides, with validation and precedence logic. Wire mode strictly rejects explicit browser and policy configuration. [1] [2] [3]
• Updates the README.md with detailed instructions and behavioral notes for using the Wire runtime, including example commands, configuration, and security caveats.

Testing for Wire Runtime:

• Introduces new test suites for the Wire runtime, covering configuration precedence, rejection of invalid settings, REPL behavior after syntax errors, and error diagnostics for both builtin and Wire modes. [1] [2] [3]

Diagnostics and Output Handling:

• Refactors diagnostics printing to allow output to arbitrary writers, not just stderr, and provides a new PrintErrorTo function for improved testability and flexibility.
• Changes the result writing logic in run.go to print available output even on error, join multiple errors (execution, copy, close), and direct all error output through the new diagnostics function. [1] [2] [3]

Build and Test Pipeline:

• Updates the GitHub Actions workflow to run tests and Go race detection as part of the build process, ensuring better CI coverage.
• Expands the Makefile's formatting targets to include the examples directory.

Command Behavior Consistency:

• Ensures the REPL uses the correct IO streams for input, output, and error, improving consistency with other commands and testability.
• Adds a test to ensure the debug command rejects Wire runtime before connecting, maintaining expected runtime restrictions.

These changes collectively provide robust, well-documented, and thoroughly tested support for executing Ferret scripts via the Wire Universal API, while maintaining clear boundaries with builtin and legacy runtimes.

[Copilot]

Copilot review overview

🔵 Needs a closer look

The alpha-runtime integration spans transport lifecycle, cancellation, diagnostics, configuration, and interactive execution, warranting final human review.

Review effort: Balanced
Findings: 1

Open (1)

• Avoid duplicating construction context cancellation errors · New

What changed in this PR

Adds Wire runtime support for local Universal API execution while preserving builtin and legacy HTTP modes.

Changes:

• Adds Wire connection, validation, lifecycle, metadata, and execution support.
• Refactors diagnostics, output handling, REPL streams, and runtime cleanup.
• Expands documentation, tests, benchmarks, examples, and CI race coverage.

File	Description
README.md	Documents Wire usage and constraints.
pkg/​runtime/​wire_endpoint.go	Validates local Wire endpoints.
pkg/​runtime/​wire_benchmark_test.go	Benchmarks Wire operations.
pkg/​runtime/​unversioned_server_test.go	Provides legacy handshake fixture.
pkg/​runtime/​uapi_metadata_test.go	Tests metadata and cancellation.
pkg/​runtime/​transport.go	Manages physical transport lifecycle.
pkg/​runtime/​source_test.go	Tests source execution and cleanup.
pkg/​runtime/​source_resources.go	Owns runtime resources.
pkg/​runtime/​source_factory.go	Constructs builtin, Wire, or legacy runtimes.
pkg/​runtime/​source_execution.go	Executes canonical source runtimes.
pkg/​runtime/​scripted_runtime_test.go	Adds runtime test double.
pkg/​runtime/​runtime.go	Routes source execution through the new factory.
pkg/​runtime/​runtime_test.go	Tests Wire factory restrictions.
pkg/​runtime/​round_trip_func_test.go	Adds HTTP transport test helper.
pkg/​runtime/​remote.go	Preserves response-close errors.
pkg/​runtime/​remote_version_test.go	Tests remote version cleanup.
pkg/​runtime/​options.go	Adds Wire options and validation.
pkg/​runtime/​metadata.go	Exposes embedded runtime metadata.
pkg/​runtime/​incompatible_handshake_test.go	Tests incompatible handshakes.
pkg/​runtime/​close_func_test.go	Adds cleanup test helper.
pkg/​runtime/​builtin.go	Adapts builtin execution to UAPI.
pkg/​runtime/​builtin_benchmark_test.go	Expands builtin benchmarks.
pkg/​repl/​write_func_test.go	Adds writer test helper.
pkg/​repl/​repl.go	Adds context-aware, stream-injected REPL execution.
pkg/​repl/​read_func_test.go	Adds reader test helper.
pkg/​repl/​metadata_test.go	Tests REPL metadata behavior.
pkg/​repl/​lifecycle_test.go	Tests REPL cancellation and disconnects.
pkg/​repl/​compatibility_test.go	Covers builtin and legacy REPL behavior.
pkg/​config/​store.go	Loads Wire and explicit configuration state.
pkg/​config/​runtime_metadata_test.go	Tests unbound environment configuration.
pkg/​config/​flags.go	Defines Wire configuration keys.
Makefile	Formats example sources.
internal/​testutil/​wirehost/​version_runtime.go	Overrides fixture version retrieval.
internal/​testutil/​wirehost/​tracked_connection.go	Tracks fixture connections.
internal/​testutil/​wirehost/​listener.go	Tracks accepted TCP clients.
internal/​testutil/​wirehost/​host.go	Implements the Wire test host.
internal/​diagnostics/​recoverable.go	Classifies recoverable query failures.
internal/​diagnostics/​portable_format.go	Formats portable diagnostic spans.
internal/​diagnostics/​diagnostics.go	Unifies native and portable diagnostics.
internal/​diagnostics/​diagnostics_test.go	Tests diagnostic rendering.
go.sum	Updates dependency checksums.
go.mod	Adds Wire/UAPI dependencies and upgrades Ferret.
examples/​wire-host/​main.go	Adds a local Wire host example.
cmd/​internal/​version/​wire_test.go	Tests runtime version selection.
cmd/​internal/​version/​version.go	Reports selected runtime metadata.
cmd/​internal/​version/​failing_writer_test.go	Adds output-failure helper.
cmd/​internal/​testutil/​testutil.go	Isolates command configuration tests.
cmd/​internal/​run/​wire_test.go	Tests Wire run modes and diagnostics.
cmd/​internal/​run/​run.go	Preserves output alongside execution errors.
cmd/​internal/​run/​result_test.go	Tests output and joined errors.
cmd/​internal/​run/​failing_close_reader_test.go	Adds reader cleanup helper.
cmd/​internal/​run/​array_diagnostics_test.go	Compares builtin and Wire diagnostics.
cmd/​internal/​repl/​wire_test.go	Tests Wire REPL reuse.
cmd/​internal/​repl/​repl.go	Passes Cobra IO streams to the REPL.
cmd/​internal/​execution/​wire_test.go	Tests Wire option precedence and rejection.
cmd/​internal/​execution/​runtime_options.go	Validates assembled runtime options.
cmd/​internal/​execution/​flags.go	Registers Wire selection flags.
cmd/​internal/​diagnostics/​diagnostics.go	Supports caller-selected diagnostic writers.
cmd/​internal/​debug/​debug_test.go	Tests early Wire rejection.
.github/​workflows/​build.yml	Adds tests and race detection to CI.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.