rooibos 0.5.0 → 0.6.0

data/lib/rooibos/cli/commands/new.rb

@@ -0,0 +1,373 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: LGPL-3.0-or-later
+#++
+
+require "open3"
+require "fileutils"
+require "pathname"
+require "optparse"
+
+module Rooibos
+  module CLI
+    module Commands # :nodoc:
+      # Scaffolds a new Rooibos TUI application.
+      #
+      # Starting a TUI project from scratch is tedious. Gem structure,
+      # test setup, executable wiring, and dependency management all
+      # take time before you write your first line of application code.
+      #
+      # This command delegates to +bundle gem+ for the boilerplate, then
+      # customizes the result for Rooibos. It creates a working Model-View-Update
+      # skeleton with a passing test.
+      #
+      # Use it to bootstrap new projects.
+      #
+      # === Example
+      #
+      #   rooibos new my_app
+      #   rooibos new my_app --no-git
+      #   rooibos new my_app --test=rspec  # warns about TestHelper
+      module New
+        # Default flags for bundle gem.
+        # Note: We use --no-bundle so we can add rooibos to Gemfile first.
+        BUNDLE_GEM_DEFAULTS = %w[
+          --exe
+          --no-coc
+          --changelog
+          --no-ext
+          --git
+          --no-mit
+          --test=minitest
+          --no-ci
+          --linter=rubocop
+          --no-bundle
+        ].freeze
+
+        # Runs the new command.
+        #
+        # [argv] Command-line arguments (expects app name as first element).
+        def self.call(argv)
+          options = parse_options(argv)
+
+          if options[:help]
+            puts usage
+            exit(0)
+          end
+
+          if argv.empty?
+            warn "Error: Missing application name"
+            warn usage
+            exit(1)
+          end
+
+          app_name = argv.shift
+          passthrough_args = argv # Remaining args passed to bundle gem
+
+          create_app(app_name, passthrough_args, options)
+        end
+
+        # Returns command-specific usage.
+        def self.usage
+          <<~USAGE
+            Usage: rooibos new <appname> [options]
+
+            Creates a new Rooibos TUI application using `bundle gem`.
+
+            Arguments:
+              <appname>   Name of the application to create
+
+            Options:
+              --help, -h  Show this help
+
+            Bundle Gem Defaults (can be overridden):
+              --exe           Create executable (enabled by default)
+              --no-coc        No Code of Conduct (default)
+              --changelog     Generate CHANGELOG.md (default)
+              --no-ext        No native extension (default)
+              --git           Initialize git repo (default)
+              --no-mit        No MIT license (default)
+              --test=minitest Use Minitest (default, recommended)
+              --no-ci         No CI config (default)
+              --linter=rubocop Use RuboCop (default)
+              --bundle        Run bundle install (default)
+
+            Any bundle gem option can be passed through, for example:
+              rooibos new my_app --no-git
+              rooibos new my_app --test=rspec  # warns about TestHelper
+
+            Note: Rooibos::TestHelper is only verified to work with Minitest.
+          USAGE
+        end
+
+        def self.parse_options(argv)
+          options = { help: false, test_framework: "minitest", skip_bundle: false }
+
+          # Extract --help before OptionParser to avoid conflicts with passthrough
+          if argv.include?("--help") || argv.include?("-h")
+            argv.delete("--help")
+            argv.delete("-h")
+            options[:help] = true
+          end
+
+          # Detect test framework from passthrough args
+          argv.each do |arg|
+            if arg.start_with?("--test=")
+              options[:test_framework] = arg.sub("--test=", "")
+            end
+          end
+
+          # Detect if user wants to skip bundle install
+          if argv.include?("--no-bundle")
+            options[:skip_bundle] = true
+          end
+
+          options
+        end
+        private_class_method :parse_options
+
+        def self.create_app(app_name, passthrough_args, options)
+          puts "Creating new Rooibos application: #{app_name}"
+
+          # Warn about non-minitest frameworks
+          test_framework = options[:test_framework].to_s
+          if %w[rspec test-unit].include?(test_framework)
+            warn "Warning: Rooibos::TestHelper has not been verified to work with #{test_framework}."
+            warn "         You may need to adapt the test helpers for your framework."
+          end
+
+          # Build bundle gem command
+          bundle_args = build_bundle_gem_args(passthrough_args)
+          cmd = ["bundle", "gem", app_name] + bundle_args
+
+          puts "Running: #{cmd.join(' ')}"
+          stdout, stderr, status = Open3.capture3(*cmd)
+          unless status.success?
+            warn "Error running bundle gem:"
+            warn stderr
+            exit(1)
+          end
+          puts stdout
+
+          # Determine the normalized gem name by looking at lib/
+          app_path = Pathname.new(app_name)
+          lib_path = app_path / "lib"
+          lib_files = Dir.glob(lib_path / "*.rb")
+          gem_name = lib_files.map { |f| File.basename(f, ".rb") }
+            .reject { |n| n.end_with?("_version") }
+            .first
+
+          unless gem_name
+            warn "Could not determine gem name from lib/ directory"
+            exit(1)
+          end
+
+          module_name = to_module_name(gem_name)
+
+          # Overwrite lib/<gem_name>.rb with Rooibos template
+          lib_file = lib_path / "#{gem_name}.rb"
+          File.write(lib_file.to_s, app_template(gem_name, module_name))
+          puts "Updated #{lib_file}"
+
+          # Update the bundler-created executable to call Rooibos.run
+          exe_file = app_path / "exe" / gem_name
+          if exe_file.exist?
+            File.write(exe_file.to_s, exe_template(gem_name, module_name))
+            puts "Updated #{exe_file}"
+          end
+
+          # Add rooibos as runtime dependency to gemspec (not Gemfile) for dev/prod parity
+          gemspec_files = Dir.glob(app_path / "*.gemspec")
+          if gemspec_files.any?
+            gemspec_file = gemspec_files.first
+            content = File.read(gemspec_file)
+
+            # Comment out placeholder lines that RubyGems 3.x validates
+            content = fix_gemspec_placeholders(content)
+
+            # Check if already has rooibos dependency
+            unless content.match?(/add_(?:runtime_)?dependency.*rooibos/)
+              # Use Gem::Version to handle prerelease versions correctly
+              segments = Gem::Version.new(Rooibos::VERSION).segments
+              minor_version = segments.first(2).map(&:to_s).join(".")
+              # Insert before the final 'end' of the Gem::Specification block
+              content = content.sub(
+                /^end\s*\z/m,
+                "\n  # https://www.rooibos.run\n  spec.add_runtime_dependency \"rooibos\", \"~> #{minor_version}\"\nend\n"
+              )
+            end
+
+            File.write(gemspec_file, content)
+            puts "Updated #{gemspec_file}"
+          end
+
+          # Run bundle install unless user passed --no-bundle
+          unless options[:skip_bundle]
+            Dir.chdir(app_path) do
+              puts "Running bundle install..."
+              system("bundle", "install")
+            end
+          end
+
+          # Update test infrastructure for Rooibos
+          if test_framework == "minitest"
+            # Add rooibos/test_helper to the project's test_helper.rb
+            test_helper = app_path / "test" / "test_helper.rb"
+            if test_helper.exist?
+              content = File.read(test_helper.to_s)
+              unless content.include?("rooibos/test_helper")
+                # Add after the gem require line
+                content = content.sub(
+                  /require\s+["']#{gem_name}["']/,
+                  "\\0\nrequire \"rooibos/test_helper\""
+                )
+                File.write(test_helper.to_s, content)
+                puts "Updated #{test_helper}"
+              end
+            end
+
+            # Replace test file with real Rooibos test
+            test_file = app_path / "test" / "test_#{gem_name}.rb"
+            if test_file.exist?
+              File.write(test_file.to_s, test_template(gem_name, module_name))
+              puts "Updated #{test_file}"
+            end
+          end
+
+          # Make initial git commit if git is enabled and bundle didn't
+          if git_enabled?(passthrough_args)
+            make_initial_commit(app_path)
+          end
+
+          puts "\nDone! Your Rooibos application is ready."
+          puts "  cd #{app_name}"
+          puts "  rooibos run"
+        end
+        private_class_method :create_app
+
+        def self.build_bundle_gem_args(passthrough_args)
+          # Start with defaults
+          args = BUNDLE_GEM_DEFAULTS.dup
+
+          # Override with user-provided args (later args win in bundle gem)
+          args + passthrough_args
+        end
+        private_class_method :build_bundle_gem_args
+
+        def self.git_enabled?(passthrough_args)
+          # Git is enabled by default unless --no-git is passed
+          !passthrough_args.include?("--no-git")
+        end
+        private_class_method :git_enabled?
+
+        def self.make_initial_commit(app_path)
+          Dir.chdir(app_path) do
+            # Check if there are uncommitted changes
+            _, _, status = Open3.capture3("git", "status", "--porcelain")
+            return unless status.success?
+
+            uncommitted, = Open3.capture3("git", "status", "--porcelain")
+            return if uncommitted.strip.empty?
+
+            # Stage and commit
+            system("git", "add", "-A", out: File::NULL, err: File::NULL)
+            system("git", "commit", "-m", "Hello, Rooibos!\n\nhttps://www.rooibos.run",
+              out: File::NULL, err: File::NULL)
+            puts "Created initial git commit"
+          end
+        end
+        private_class_method :make_initial_commit
+
+        def self.to_module_name(gem_name)
+          gem_name.split(/[-_]/).map(&:capitalize).join
+        end
+        private_class_method :to_module_name
+
+        # Fixes gemspec placeholder lines that RubyGems 3.x+ rejects.
+        # Required fields get valid placeholder values; optional metadata block is deleted.
+        def self.fix_gemspec_placeholders(content)
+          result = content
+
+          # Replace required field TODOs with valid placeholders
+          result = result.gsub(
+            /^(\s*spec\.summary\s*=\s*)"TODO:[^"]*"/,
+            '\1"A Rooibos TUI application"'
+          )
+          result = result.gsub(
+            /^(\s*spec\.description\s*=\s*)"TODO:[^"]*"/,
+            '\1"A terminal user interface application built with Rooibos"'
+          )
+          result = result.gsub(
+            /^(\s*spec\.homepage\s*=\s*)"TODO:[^"]*"/,
+            '\1"https://www.rooibos.run"'
+          )
+          result = result.gsub(
+            /^(\s*spec\.authors\s*=\s*)\["TODO:[^\]]*"\]/,
+            '\1["Author"]'
+          )
+          result = result.gsub(
+            /^(\s*spec\.email\s*=\s*)\["TODO:[^\]]*"\]/,
+            '\1["author@example.com"]'
+          )
+
+          # Delete the entire metadata block (optional and causes validation issues)
+          result.gsub(/^\s*spec\.metadata\["[^"]*"\]\s*=.*\n/, "")
+        end
+        private_class_method :fix_gemspec_placeholders
+
+        def self.exe_template(gem_name, module_name)
+          <<~RUBY
+            #!/usr/bin/env ruby
+            # frozen_string_literal: true
+
+            require "#{gem_name}"
+            Rooibos.run(#{module_name})
+          RUBY
+        end
+        private_class_method :exe_template
+
+        def self.app_template(gem_name, module_name)
+          <<~RUBY
+            # frozen_string_literal: true
+
+            require "rooibos"
+            require "rooibos/welcome"
+
+            # To get started, replace the following lines with your own code
+            # and remove the `require "rooibos/welcome"` line from above
+            module #{module_name}
+              Model  = Rooibos::Welcome::Model
+              View   = Rooibos::Welcome::View
+              Update = Rooibos::Welcome::Update
+              Init   = Rooibos::Welcome::Init
+            end
+          RUBY
+        end
+        private_class_method :app_template
+
+        def self.test_template(gem_name, module_name)
+          <<~RUBY
+            # frozen_string_literal: true
+
+            require "test_helper"
+
+            class Test#{module_name} < Minitest::Test
+              include Rooibos::TestHelper
+
+              def test_it_exits_with_ctrl_c
+                with_test_terminal do
+                  inject_key(:ctrl_c)
+                  Rooibos.run(#{module_name})
+                  assert true, "Should reach this point without hanging."
+                end
+              end
+            end
+          RUBY
+        end
+        private_class_method :test_template
+      end
+    end
+  end
+end

data/lib/rooibos/cli/commands/run.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: LGPL-3.0-or-later
+#++
+
+require "pathname"
+require "rbconfig"
+
+module Rooibos
+  module CLI
+    module Commands
+      # Runs the Rooibos application in the current directory.
+      #
+      # Developers switch between editor and terminal constantly. Typing
+      # +bundle exec exe/my_app+ every time is tedious and error-prone.
+      #
+      # This command finds the executable in +exe/+ and runs it via bundler.
+      # It walks up the directory tree to find the project root, then
+      # executes the first executable it finds.
+      #
+      # Use it from any directory within your project.
+      #
+      # === Example
+      #
+      #   rooibos run
+      module Run
+        # Runs the run command.
+        #
+        # [argv] Command-line arguments.
+        def self.call(argv)
+          if ["--help", "-h"].include?(argv.first)
+            puts usage
+            exit(0)
+          end
+
+          run_app
+        end
+
+        # Returns command-specific usage.
+        def self.usage # :nodoc:
+          <<~USAGE
+            Usage: rooibos run [options]
+
+            Runs the Rooibos application in the current directory.
+
+            Options:
+              --help, -h  Show this help
+          USAGE
+        end
+        private_class_method :usage
+
+        def self.run_app # :nodoc:
+          project_root = find_project_root
+          unless project_root
+            warn "Error: Not in a Rooibos project directory"
+            warn "Could not find a .gemspec or Gemfile"
+            exit(1)
+          end
+
+          exe_dir = project_root / "exe"
+          unless exe_dir.directory?
+            warn "Error: No exe/ directory found"
+            exit(1)
+          end
+
+          executables = Dir.glob(exe_dir / "*").select { |f| File.executable?(f) }
+          if executables.empty?
+            warn "Error: No executable found in exe/"
+            exit(1)
+          end
+
+          executable = executables.first
+          puts "Running #{File.basename(executable)}..."
+
+          # Run with bundler/setup for gem activation, but skip bundle exec CLI
+          # to produce clean stack traces without bundler/thor frames
+          Dir.chdir(project_root)
+          exec(RbConfig.ruby, "-rbundler/setup", executable)
+        end
+        private_class_method :run_app
+
+        def self.find_project_root # :nodoc:
+          current = Pathname.pwd
+          loop do
+            return current if (current / "Gemfile").exist?
+            return current if Dir.glob(current / "*.gemspec").any?
+            parent = current.parent
+            return nil if parent == current
+            current = parent
+          end
+        end
+        private_class_method :find_project_root
+      end
+    end
+  end
+end

data/lib/rooibos/cli.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: LGPL-3.0-or-later
+#++
+
+require_relative "version"
+require_relative "cli/commands/new"
+require_relative "cli/commands/run"
+
+module Rooibos
+  # Entry point for the Rooibos command-line interface.
+  #
+  # Rooibos provides a CLI for common development tasks. Rather than
+  # remembering incantations for each tool, use a single command.
+  #
+  # This module dispatches to subcommands. It routes <tt>new</tt> to
+  # project scaffolding and <tt>run</tt> to application execution.
+  #
+  # Use it via the +rooibos+ executable.
+  #
+  # === Example
+  #
+  #   # From terminal:
+  #   rooibos new my_app
+  #   cd my_app
+  #   rooibos run
+  #
+  #   # Programmatic access:
+  #   Rooibos::CLI.call(["new", "my_app"])
+  #   Rooibos::CLI.call(["run"])
+  module CLI
+    # Maps command names to handler modules.
+    COMMANDS = { # :nodoc:
+      "new" => Commands::New,
+      "run" => Commands::Run,
+    }.freeze
+
+    # Entry point for the CLI.
+    #
+    # [argv] Command-line arguments array.
+    def self.call(argv)
+      command_name = argv.shift
+
+      case command_name
+      when "--version", "-v"
+        puts "Rooibos #{Rooibos::VERSION}"
+      when "--help", "-h", nil
+        puts usage
+      else
+        command = COMMANDS[command_name]
+        if command
+          command.call(argv)
+        else
+          warn "Unknown command: #{command_name}"
+          warn usage
+          exit(1)
+        end
+      end
+    end
+
+    # Returns the main usage message.
+    def self.usage
+      <<~USAGE
+        Usage: rooibos <command> [options]
+
+        Commands:
+          new <appname>  Create a new Rooibos application
+          run            Run the application in the current directory
+
+        Options:
+          --version, -v  Show version
+          --help, -h     Show this help
+      USAGE
+    end
+  end
+end

data/lib/rooibos/command/all.rb

@@ -11,31 +11,36 @@ module Rooibos
     All = Data.define(:envelope, :commands, :nested) do
       include Custom
 
-      def self.new(tag, *args)
-        # DWIM: detect nested vs splatted based on call-site arity
-        if args.size == 1 && args.first.is_a?(Array)
-          commands = args.first
-          nested = true
-        else
-          commands = args
-          nested = false
-        end
+      class << self
+        undef_method :new
+
+        def new(tag, *args)
+          # DWIM: detect nested vs splatted based on call-site arity
+          if args.size == 1 && args.first.is_a?(Array)
+            commands = args.first
+            nested = true
+          else
+            commands = args
+            nested = false
+          end
 
-        if RatatuiRuby::Debug.enabled?
-          commands.each do |cmd|
-            unless Ractor.shareable?(cmd)
-              raise Rooibos::Error::Invariant,
-                "Command is not Ractor-shareable: #{cmd.inspect}\n" \
-                  "Use Ractor.make_shareable or a Data.define command."
+          if RatatuiRuby::Debug.enabled?
+            commands.each do |cmd|
+              unless Ractor.shareable?(cmd)
+                raise Rooibos::Error::Invariant,
+                  "Command is not Ractor-shareable: #{cmd.inspect}\n" \
+                    "Use Ractor.make_shareable or a Data.define command."
+              end
             end
           end
-        end
 
-        instance = allocate
-        instance.__send__(:initialize, envelope: tag, commands: commands.freeze, nested:)
-        instance
+          instance = allocate
+          instance.__send__(:initialize, envelope: tag, commands: commands.freeze, nested:)
+          instance
+        end
       end
 
+      # Executes the command, running all children in parallel.
       def call(out, token)
         # Early return for empty commands - prevents hang from zip_futures([])
         if commands.empty?
@@ -58,7 +63,7 @@ module Rooibos
         all_done = Concurrent::Promises.zip_futures(*futures)
         Concurrent::Promises.any_event(all_done, token.origin).wait
 
-        return out.put(Command.cancel(self)) if token.canceled?
+        return out.put(Message::Canceled.new(command: self)) if token.canceled?
 
         shareable_results = Ractor.make_shareable(all_done.value!)
         response = Message::All.new(envelope:, results: shareable_results, nested:)

data/lib/rooibos/command/batch.rb

@@ -15,7 +15,7 @@ module Rooibos
     #
     # This command runs children in parallel. Each child sends its own messages
     # independently. The batch completes when all children finish or when
-    # cancellation fires. On cancellation, emits <tt>Command.cancel(self)</tt>.
+    # cancellation fires. On cancellation, emits <tt>Message::Canceled</tt>.
     #
     # Use it for parallel fetches, concurrent refreshes, or any work that
     # does not need coordinated results.
@@ -37,39 +37,40 @@ module Rooibos
     class Batch < Data.define(:commands) do
       include Custom
 
-      # Initialize
-      def self.new(*args)
-        # DWIM: accept (cmd1, cmd2) or ([cmd1, cmd2])
-        commands = (args.size == 1 && args.first.is_a?(Array)) ? args.first : args
+      class << self
+        undef_method :new
 
-        if RatatuiRuby::Debug.enabled?
-          commands.each do |cmd|
-            unless Ractor.shareable?(cmd)
-              raise Rooibos::Error::Invariant,
-                "Command is not Ractor-shareable: #{cmd.inspect}\n" \
-                  "Use Ractor.make_shareable or a Data.define command."
+        # Initialize
+        def new(*args)
+          # DWIM: accept (cmd1, cmd2) or ([cmd1, cmd2])
+          commands = (args.size == 1 && args.first.is_a?(Array)) ? args.first : args
+
+          if RatatuiRuby::Debug.enabled?
+            commands.each do |cmd|
+              unless Ractor.shareable?(cmd)
+                raise Rooibos::Error::Invariant,
+                  "Command is not Ractor-shareable: #{cmd.inspect}\n" \
+                    "Use Ractor.make_shareable or a Data.define command."
+              end
             end
           end
-        end
 
-        instance = allocate
-        instance.__send__(:initialize, commands: commands.freeze)
-        instance
+          instance = allocate
+          instance.__send__(:initialize, commands: commands.freeze)
+          instance
+        end
       end
 
       # Call it
       def call(out, token)
-        futures = commands.map do |command|
-          Concurrent::Promises.future { command.call(out, token) }
-        end
+        handles = commands.map { |cmd| out.standing(cmd, token) }
+        out.wait(*handles, token:)
 
-        all_done = Concurrent::Promises.zip_futures(*futures)
-        Concurrent::Promises.any_event(all_done, token.origin).wait
-
-        # Re-raise any child exception for runtime to wrap in Command::Error
-        futures.each { |f| raise f.reason if f.rejected? }
-
-        out.put(Command.cancel(self)) if token.canceled?
+        if token.canceled?
+          out.put(Message::Canceled.new(command: self))
+        else
+          out.put(Message::Batch.new(command: self))
+        end
       end
     end
     end