Exit through an injectable kernel; add Launcher for Aruba testing (1 of 4)

[kigster]

Proposal 1 of 4 in the dry-cli plugin-hooks series.

Upstream issue/forum thread: pending (per CONTRIBUTING.md this is discussed on the forum before going to dry-rb).

Summary

CLI exits go through an injectable kernel, and a Launcher runs a CLI with Aruba's in-process signature.

 Dry::CLI#call(arguments:, stdout:, stderr:, stdin:, kernel: Kernel)
   perform_registry / perform_command
     parse
     help           → raise Halt(0)
     error          → raise Halt(1)
     spell_checker  → raise Halt(1)
   rescue Halt      → kernel.exit(status)
   rescue Signal    → kernel.exit(128 + signo)

Explanation

• Halt is private. It exists because a test kernel's exit returns: without it, execution would fall through the help screen into code expecting a parsed command.

• kernel: is an auto_initialize keyword (Free up #initialize for command subclasses #167), so Command#kernel is set before #initialize and never reaches it. Private Command#exit goes through it.

Launcher

Launcher is an intermediate class that swaps out standard streams (stdin, stdout, stderr, and additionally, Kernel) so that in tests the streams could be replaced with StringIO, and Kernel.exit be a no-op.

This lets you use another gem called aruba for proper CLI integration testing of the command, without the penalty of a fork(). With this Launcher pattern, Aruba can drive the gem in a single process, making tests much, much faster.

Example of how to configure Aruba

MyApp::Launcher = Dry::CLI::Launcher[MyApp::Commands]   
MyApp::Launcher.new(ARGV).execute!

# spec/spec_helper.rb
Aruba.configure do |config|
  config.command_launcher = :in_process
  config.main_class       = MyApp::Launcher
end

• Launcher[target, stdin:, stdout:, stderr:, kernel:] pins defaults for .new(argv); unpinned ones take the globals when the launcher is created. Aruba passes all five, so its StringIOs win.

• #execute! exits 0 unless the CLI already exited; exceptions propagate. No global stream swapping.

Evidence

• Before: Dry.CLI(registry).call(arguments: ["x", "-h"], kernel: fake) → NoMethodError (no kernel:); in-process Aruba runs and ends the test process on exit.

• After: spec/unit/dry/cli/kernel_spec.rb (14), launcher_spec.rb (14), spec/integration/launcher_spec.rb (3, real Aruba in-process). Full suite: 631 examples, 0 failures; rubocop clean.

Notes

• Adds a test dependency on aruba gem

See

Blog Post on testing CLI Gems with Aruba

Note

Important

This and every one of my PRs has been produced in a pair-programming session with Claude, reviewed by me and another agent to be sure.