rooibos 0.5.0 → 0.6.1

data/generate_tutorial_stubs.rb

@@ -0,0 +1,126 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "fileutils"
+
+# Parse tutorial structure from documentation_plan.md
+TUTORIAL_FILES = {
+  "index.md" => { title: "Tutorial: Build a File Browser", story: nil },
+  "01_project_setup.md" => { title: "Project Setup", story: "-4" },
+  "02_hello_world.md" => { title: "Hello World", story: "-3" },
+  "03_static_file_list.md" => { title: "Static File List", story: "-2" },
+  "04_arrow_navigation.md" => { title: "Arrow Navigation", story: "-1" },
+  "05_real_files.md" => { title: "Real Files", story: "0" },
+  "06_safe_refactoring.md" => { title: "Safe Refactoring", story: "4a" },
+  "07_red_first_tdd.md" => { title: "Red-First TDD", story: "4b" },
+  "08_file_metadata.md" => { title: "File Metadata", story: "5" },
+  "09_text_preview.md" => { title: "Text Preview", story: "6" },
+  "10_directory_tree.md" => { title: "Directory Tree", story: "7" },
+  "11_pane_focus.md" => { title: "Pane Focus", story: "8" },
+  "12_sorting.md" => { title: "Sorting", story: "9" },
+  "13_filtering.md" => { title: "Filtering", story: "10" },
+  "14_toggle_hidden.md" => { title: "Toggle Hidden Files", story: "11" },
+  "15_text_input_widget.md" => { title: "Text Input Widget", story: "12" },
+  "16_rename_files.md" => { title: "Rename Files", story: "13" },
+  "17_confirmation_dialogs.md" => { title: "Confirmation Dialogs", story: "14" },
+  "18_progress_indicators.md" => { title: "Progress Indicators", story: "15" },
+  "19_atomic_operations.md" => { title: "Atomic Operations", story: "16" },
+  "20_external_editor.md" => { title: "External Editor", story: "17" },
+  "21_modal_overlays.md" => { title: "Modal Overlays", story: "18" },
+  "22_error_handling.md" => { title: "Error Handling", story: "19" },
+  "23_terminal_capabilities.md" => { title: "Terminal Capabilities", story: "23" },
+  "24_mouse_events.md" => { title: "Mouse Events", story: "20" },
+  "25_resize_events.md" => { title: "Resize Events", story: "21" },
+  "26_loading_states.md" => { title: "Loading States", story: "22" },
+  "27_performance.md" => { title: "Performance", story: "24" },
+  "28_color_schemes.md" => { title: "Color Schemes", story: "26" },
+  "29_configuration.md" => { title: "Configuration", story: "27" },
+  "30_going_further.md" => { title: "Going Further", story: nil },
+}
+
+# Parse stories from file_browser_stories.md
+stories_content = File.read("doc/contributors/specs/file_browser_stories.md")
+
+# Extract each story
+stories = {}
+current_story = nil
+current_content = []
+
+stories_content.each_line do |line|
+  if line =~ /^## Story (-?\d+[ab]?): (.+)$/
+    # Save previous story
+    if current_story
+      stories[current_story] = current_content.join
+    end
+
+    current_story = $1
+    current_content = [line]
+  elsif current_story
+    current_content << line
+
+    # Stop at the next story or end of stories section
+    if line =~ /^---$/ && current_content.size > 5
+      # Check if next section is another story or implementation notes
+      peek_ahead = stories_content.lines[stories_content.lines.index(line) + 1]
+      if peek_ahead && !peek_ahead.start_with?("## Story")
+        stories[current_story] = current_content.join
+        break if peek_ahead.start_with?("## Implementation Notes")
+      end
+    end
+  end
+end
+
+# Save last story
+stories[current_story] = current_content.join if current_story
+
+# Create tutorial directory
+FileUtils.mkdir_p("doc/tutorial")
+
+# Generate stub files
+TUTORIAL_FILES.each do |filename, meta|
+  filepath = "doc/tutorial/#{filename}"
+
+  # Determine previous/next files
+  files_list = TUTORIAL_FILES.keys
+  current_index = files_list.index(filename)
+  prev_file = (current_index > 0) ? files_list[current_index - 1] : nil
+  next_file = (current_index < files_list.size - 1) ? files_list[current_index + 1] : nil
+
+  prev_title = prev_file ? TUTORIAL_FILES[prev_file][:title] : nil
+  next_title = next_file ? TUTORIAL_FILES[next_file][:title] : nil
+
+  # Get story content if applicable
+  story_section = ""
+  if meta[:story]
+    story_key = meta[:story]
+    if stories[story_key]
+      story_section = "\n## User Stories\n\n#{stories[story_key]}\n"
+    end
+  end
+
+  # Generate stub content
+  content = <<~MARKDOWN
+    <!--
+      SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+      SPDX-License-Identifier: CC-BY-SA-4.0
+    -->
+
+    # #{meta[:title]}
+
+
+    By the end of this guide, you will:
+
+    - TODO: Write learning objectives
+
+    > ⚠️ **This page is a stub.** Help us write it! See the [Documentation Plan](../contributors/documentation_plan.md) and [Style Guide](../contributors/documentation_style.md).
+    #{story_section}
+    ---
+
+    #{prev_file ? "[**Previous:** #{prev_title}](./#{prev_file})" : ''} | #{next_file ? "[**Next:** #{next_title}](./#{next_file})" : ''}
+  MARKDOWN
+
+  File.write(filepath, content)
+  puts "Created #{filepath}"
+end
+
+puts "\nDone! Created #{TUTORIAL_FILES.size} tutorial stub files."

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