smol 1.0.0

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rake/testtask"
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << "test"
+  t.libs << "lib"
+  t.test_files = FileList["test/**/*_test.rb"]
+end
+
+task default: :test

data/lib/smol/app.rb

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+module Smol
+  class App
+    class << self
+      def inherited(subclass)
+        super
+        subclass.instance_variable_set(:@commands, [])
+        subclass.instance_variable_set(:@checks, [])
+        subclass.instance_variable_set(:@mounts, {})
+
+        parent_module = find_parent_module(subclass)
+        setup_registry_methods(parent_module, subclass) if parent_module
+      end
+
+      def banner(text = nil)
+        @banner = text if text
+        @banner || ""
+      end
+
+      def cli(enabled = nil)
+        @cli_enabled = enabled unless enabled.nil?
+        @cli_enabled.nil? ? true : @cli_enabled
+      end
+
+      def repl(enabled = nil)
+        @repl_enabled = enabled unless enabled.nil?
+        @repl_enabled.nil? ? true : @repl_enabled
+      end
+
+      def boot(mode = nil)
+        @boot_mode = mode if mode
+        @boot_mode || :help
+      end
+
+      def history_file(path = nil)
+        @history_file = path if path
+        @history_file
+      end
+
+      def config
+        @config ||= Config.new
+      end
+
+      def commands
+        @commands ||= []
+      end
+
+      def checks
+        @checks ||= []
+      end
+
+      def mounts
+        @mounts ||= {}
+      end
+
+      def mount(app_class, as:)
+        mounts[as.to_s] = app_class
+      end
+
+      def find_command(name)
+        # Check for mounted app prefix (e.g., "admin:users")
+        if name.include?(":")
+          prefix, sub_name = name.split(":", 2)
+          if mounts[prefix]
+            return mounts[prefix].find_command(sub_name)
+          end
+        end
+
+        commands.find { |c| c.matches?(name) }
+      end
+
+      def find_mount(name)
+        mounts[name.to_s]
+      end
+
+      def register_command(command_class)
+        commands << command_class
+      end
+
+      def register_check(check_class)
+        checks << check_class
+      end
+
+      def register(command_class)
+        @explicit_registration = true
+        commands << command_class
+      end
+
+      def explicit_registration?
+        @explicit_registration || false
+      end
+
+      private
+
+      def find_parent_module(subclass)
+        parts = subclass.name&.split("::")
+        return nil unless parts && parts.size > 1
+
+        parent_name = parts[0..-2].join("::")
+        begin
+          Object.const_get(parent_name)
+        rescue NameError
+          nil
+        end
+      end
+
+      def setup_registry_methods(parent_module, app_class)
+        unless parent_module.respond_to?(:register_command)
+          parent_module.define_singleton_method(:register_command) do |cmd|
+            app_class.register_command(cmd)
+          end
+        end
+        unless parent_module.respond_to?(:register_check)
+          parent_module.define_singleton_method(:register_check) do |check|
+            app_class.register_check(check)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/smol/app_lookup.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Smol
+  module AppLookup
+    private
+
+    def app_class
+      parts = self.class.name.split("::")
+      parent = Object.const_get(parts.first)
+      parent.const_get(:App)
+    end
+  end
+end

data/lib/smol/check.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module Smol
+  class Check
+    include AppLookup
+
+    class << self
+      def inherited(subclass)
+        super
+        register_to_app(subclass)
+      end
+
+      private
+
+      def register_to_app(subclass)
+        parts = subclass.name&.split("::")
+        return unless parts && parts.size > 1
+
+        parts[0..-2].size.times do |i|
+          candidate_name = parts[0..-(i + 2)].join("::")
+          begin
+            candidate = Object.const_get(candidate_name)
+          rescue NameError
+            next
+          end
+
+          if candidate.respond_to?(:register_check)
+            app_class = find_app_class_for(candidate)
+            return if app_class&.explicit_registration?
+
+            candidate.register_check(subclass)
+            return
+          end
+        end
+      end
+
+      def find_app_class_for(candidate)
+        return candidate if candidate.respond_to?(:explicit_registration?)
+
+        if candidate.const_defined?(:App, false)
+          app = candidate.const_get(:App)
+          return app if app.respond_to?(:explicit_registration?)
+        end
+        nil
+      end
+
+      public
+
+      def check_name
+        name.split("::").last
+          .gsub(/([A-Z]+)([A-Z][a-z])/, '\1_\2')
+          .gsub(/([a-z\d])([A-Z])/, '\1_\2')
+          .downcase
+          .tr("_", " ")
+      end
+    end
+
+    def pass(message)
+      CheckResult.new(passed: true, message: message)
+    end
+
+    def fail(message)
+      CheckResult.new(passed: false, message: message)
+    end
+
+    def config
+      app_class.config
+    end
+  end
+end

data/lib/smol/check_result.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Smol
+  CheckResult = Struct.new(:passed, :message, keyword_init: true) do
+    def passed?
+      passed
+    end
+
+    def failed?
+      !passed
+    end
+
+    def to_s
+      status = passed? ? "passed" : "failed"
+      "#{status}: #{message}"
+    end
+  end
+end

data/lib/smol/cli.rb

@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+
+module Smol
+  class CLI
+    include Output
+    include ConfigDisplay
+    using Colors
+
+    def initialize(app, prompt:, history: true)
+      @app = app
+      @prompt = prompt
+      @history = history
+    end
+
+    def run(args)
+      if args.empty?
+        if @app.repl
+          REPL.new(@app, prompt: @prompt, history: @history, history_file: history_file_path).run
+        else
+          usage
+          exit 1
+        end
+        return
+      end
+
+      unless @app.cli
+        failure "CLI mode is disabled"
+        hint "run without arguments for interactive mode" if @app.repl
+        exit 1
+      end
+
+      cmd_name, *cmd_args = args
+
+      case cmd_name
+      when "help", "-h", "--help"
+        usage
+        exit 1
+      when "config"
+        show_config
+        return
+      when "config:set"
+        set_config(cmd_args[0], cmd_args[1])
+        return
+      end
+
+      klass = @app.find_command(cmd_name)
+
+      if klass.nil?
+        usage
+        exit 1
+      end
+
+      positional, opts = klass.parse_options(cmd_args)
+      result = klass.new.call(*positional, **opts)
+
+      if result == true || result == false
+        exit(result ? 0 : 1)
+      end
+    end
+
+    private
+
+    def usage
+      banner @app.banner
+
+      out.puts <<~USAGE
+        #{@prompt.bold} - CLI app
+
+        #{"usage:".bold}
+          ./#{@prompt}.rb              start interactive mode
+          ./#{@prompt}.rb <command>    run a single command
+
+        #{"commands:".bold}
+      USAGE
+
+      grouped = @app.commands.group_by(&:group)
+      ungrouped = grouped.delete(nil) || []
+
+      ungrouped.each do |cmd|
+        out.puts "  #{cmd.usage.ljust(34)}#{cmd.desc}"
+      end
+
+      grouped.keys.sort.each do |group_name|
+        nl
+        out.puts "  #{group_name}:".bold
+        grouped[group_name].each do |cmd|
+          out.puts "    #{cmd.usage.ljust(32)}#{cmd.desc}"
+        end
+      end
+
+      if @app.mounts.any?
+        nl
+        out.puts "  #{"sub-apps:".bold}"
+        @app.mounts.each do |name, app_class|
+          out.puts "    #{(name + ":*").ljust(32)}#{app_class.banner.empty? ? name : app_class.banner}"
+        end
+      end
+
+      out.puts "  #{"config".ljust(34)}show current config"
+      out.puts "  #{"config:set <key> <value>".ljust(34)}set a config value"
+
+      nl
+      show_config
+      nl
+
+      out.puts "#{"environment:".bold}"
+
+      @app.config.each do |key, _, setting|
+        line = "  #{key.to_s.upcase}"
+        line += " - #{setting[:desc]}" if setting[:desc]
+        out.puts line
+      end
+    end
+
+    def history_file_path
+      @app.history_file || File.expand_path("~/.smol_#{@prompt}_history")
+    end
+  end
+end

data/lib/smol/coercion.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Smol
+  module Coercion
+    TRUTHY_VALUES = %w[true 1 yes].freeze
+
+    def coerce_value(raw, type)
+      case type
+      when :integer
+        raw.to_i
+      when :boolean
+        TRUTHY_VALUES.include?(raw.to_s.downcase)
+      else
+        raw
+      end
+    end
+  end
+end

data/lib/smol/colors.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Smol
+  module Colors
+    refine String do
+      def green
+        "\e[32m#{self}\e[0m"
+      end
+
+      def red
+        "\e[31m#{self}\e[0m"
+      end
+
+      def yellow
+        "\e[33m#{self}\e[0m"
+      end
+
+      def bold
+        "\e[1m#{self}\e[0m"
+      end
+
+      def dim
+        "\e[2m#{self}\e[0m"
+      end
+    end
+  end
+end

data/lib/smol/command.rb

@@ -0,0 +1,292 @@
+# frozen_string_literal: true
+
+module Smol
+  class Command
+    include AppLookup
+
+    class << self
+      include Coercion
+
+      def inherited(subclass)
+        super
+        subclass.prepend ErrorHandler
+        subclass.prepend Callbacks
+        subclass.prepend AutoMessage
+        register_to_app(subclass)
+      end
+
+      private
+
+      def register_to_app(subclass)
+        parts = subclass.name&.split("::")
+        return unless parts && parts.size > 1
+
+        parts[0..-2].size.times do |i|
+          candidate_name = parts[0..-(i + 2)].join("::")
+          begin
+            candidate = Object.const_get(candidate_name)
+          rescue NameError
+            next
+          end
+
+          if candidate.respond_to?(:register_command)
+            app_class = find_app_class_for(candidate)
+            return if app_class&.explicit_registration?
+
+            candidate.register_command(subclass)
+            return
+          end
+        end
+      end
+
+      def find_app_class_for(candidate)
+        return candidate if candidate.respond_to?(:explicit_registration?)
+
+        if candidate.const_defined?(:App, false)
+          app = candidate.const_get(:App)
+          return app if app.respond_to?(:explicit_registration?)
+        end
+        nil
+      end
+
+      public
+
+      def command_name(text = nil)
+        if text
+          @command_name = text
+        else
+          @command_name || derive_command_name
+        end
+      end
+
+      def title(text = nil)
+        @title = text if text
+        @title
+      end
+
+      def explain(text = nil)
+        @explain = text if text
+        @explain
+      end
+
+      def aliases(*args)
+        @aliases = args if args.any?
+        @aliases || []
+      end
+
+      def args(*args)
+        @args = args if args.any?
+        @args || []
+      end
+
+      def option(name, short: nil, type: :string, default: nil, desc: nil)
+        @options ||= {}
+        @options[name] = { short: short, type: type, default: default, desc: desc }
+      end
+
+      def options
+        @options || {}
+      end
+
+      def desc(text = nil)
+        @desc = text if text
+        @desc || ""
+      end
+
+      def group(text = nil)
+        @group = text if text
+        @group
+      end
+
+      def before_action(method_name)
+        @before_actions ||= []
+        @before_actions << method_name
+      end
+
+      def before_actions
+        @before_actions || []
+      end
+
+      def after_action(method_name)
+        @after_actions ||= []
+        @after_actions << method_name
+      end
+
+      def after_actions
+        @after_actions || []
+      end
+
+      def matches?(input)
+        input == command_name.to_s || aliases.map(&:to_s).include?(input)
+      end
+
+      def usage
+        parts = [command_name]
+        parts += args.map { |a| "<#{a}>" }
+        options.each do |name, opt|
+          flag = opt[:short] ? "-#{opt[:short]}/--#{name}" : "--#{name}"
+          parts << "[#{flag}]"
+        end
+        parts.join(" ")
+      end
+
+      def parse_options(argv)
+        positional = []
+        opts = options.transform_values { |o| o[:default] }
+
+        i = 0
+        while i < argv.length
+          arg = argv[i]
+          if arg.start_with?("--")
+            key, value = arg[2..].split("=", 2)
+            key = key.tr("-", "_").to_sym
+            if options[key]
+              value ||= argv[i += 1]
+              opts[key] = coerce_value(value, options[key][:type])
+            end
+          elsif arg.start_with?("-") && arg.length == 2
+            short = arg[1]
+            opt_name = options.find { |_, o| o[:short]&.to_s == short }&.first
+            if opt_name
+              value = argv[i += 1]
+              opts[opt_name] = coerce_value(value, options[opt_name][:type])
+            end
+          else
+            positional << arg
+          end
+          i += 1
+        end
+
+        [positional, opts]
+      end
+
+      def rescue_from(*exceptions, with: nil, &block)
+        handler = block || with
+        raise ArgumentError, "rescue_from requires a block or :with handler" unless handler
+
+        @error_handlers ||= []
+        exceptions.each do |exception|
+          @error_handlers << [exception, handler]
+        end
+      end
+
+      def error_handlers
+        @error_handlers || []
+      end
+
+      private
+
+      def derive_command_name
+        return "anonymous" unless name
+
+        name.split("::").last
+          .gsub(/([A-Z]+)([A-Z][a-z])/, '\1_\2')
+          .gsub(/([a-z\d])([A-Z])/, '\1_\2')
+          .downcase
+      end
+    end
+
+    module AutoMessage
+      def call(*args, **opts)
+        if self.class.title
+          header self.class.title
+          desc self.class.explain if self.class.explain
+          nl
+        end
+        super
+      end
+    end
+
+    module Callbacks
+      def call(*args, **opts)
+        self.class.before_actions.each do |method_name|
+          result = send(method_name, *args, **opts)
+          return result if result == false
+        end
+
+        result = super
+
+        self.class.after_actions.each do |method_name|
+          send(method_name, *args, result: result, **opts)
+        end
+
+        result
+      end
+    end
+
+    module ErrorHandler
+      def call(*args, **opts)
+        super
+      rescue => e
+        handler = find_error_handler(e)
+        if handler
+          if handler.is_a?(Symbol)
+            send(handler, e)
+          else
+            instance_exec(e, &handler)
+          end
+        else
+          raise
+        end
+      end
+
+      private
+
+      def find_error_handler(error)
+        self.class.error_handlers.each do |exception_class, handler|
+          return handler if error.is_a?(exception_class)
+        end
+        nil
+      end
+    end
+
+    include Output
+    include Input
+
+    def config
+      app_class.config
+    end
+
+    def app
+      app_class
+    end
+
+    def checking(name)
+      warning "checking: #{name}"
+      nl
+    end
+
+    def dropping(target)
+      warning "dropping: #{target}"
+      nl
+    end
+
+    def done(hint_text = nil)
+      nl
+      success "done"
+      hint hint_text if hint_text
+    end
+
+    def checks_passed?(all_passed, pass_hint: nil, fail_hint: nil)
+      nl
+      if all_passed
+        success "all checks passed"
+        hint pass_hint if pass_hint
+      else
+        failure "some checks failed"
+        hint fail_hint if fail_hint
+      end
+      all_passed
+    end
+
+    def run_checks(*check_classes, args: [])
+      results = check_classes.map do |klass|
+        result = klass.new(*args).call
+        check_result(klass.check_name, result)
+        nl
+        result.passed?
+      end
+      results.all?
+    end
+  end
+end