Exit through an injectable kernel; add Launcher (1/4 extensibility API)

[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 allows using another gem calleed aruba for proper CLI integration testing of the command, except without the penalty of a fork(). Given this type of Launcher pattern, Aruba is able to use it to drive the gem in a single process, making the tests much much faster.

Example on 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 end 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