ergane 0.0.1 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6f27bb356ea374b87bf0a12ad73bc945e518dee66aa18797b5f9b06a197de896
-  data.tar.gz: 2de58095dd7014c321d13fcac71f9d16019db72cd6feb0896bafea5f9ae19d6e
+  metadata.gz: 53b7a242e903c28ff9ddb5f33ee399c044fd618f0420cd3868cecb02c4e277e6
+  data.tar.gz: 9f8e7b16cc0f64f3547b98e41d973f4b90528215e516873600eb6e953bd2141a
 SHA512:
-  metadata.gz: 3a3431e9dd63b745dc3765a83c98c0d3ed3d60837373d12b69371f1df05e5718be8b2fd5007808e4383ba8d77c0fd6997ba7dc867e317b5b598fc80921429161
-  data.tar.gz: fa7972b5a4019cff455ca2f0631181cb3ce49192a56ee01eb549c22827fbc8d41b77cc86d089178d04e2b63474626faab18dd3acbe45be12aedaec5a37254955
+  metadata.gz: fdcf833f1190263dc9f37f470c03d7d150e566175d927e2fec39c036a22111fca8b59c7af4d64a1c1c66af1a455eecb257f66cf2c5276f0f672a513eda123e9a
+  data.tar.gz: c85a0eb19d99c6c5424e40655a6c64f33591e04a0d11d576076e2e9a03d2e9ed4f8b26080c21b052145fdff3097e4bd01687226e31abaf84f77013e155954dd9

data/CHANGELOG.md

@@ -1,5 +1,28 @@
+# CHANGELOG
+
 ## [Unreleased]
 
-## [0.1.0] - 2023-04-26
+## [0.1.0] - 2026-05-25
+
+First release of the rewritten framework. A near-complete rewrite of the
+original `0.0.1` proof of concept.
+
+### Added
+- Dual DSL: class-based and block-based command definitions, both producing the same command tree
+- Zeitwerk autoloading
+- Recursive subcommand resolution via Runner
+- Tool base class with auto-created command base (`MyTool::Command`)
+- Custom `command_class` for shared command behavior
+- Abstract commands for grouping shared options
+- Colorized help output with box-drawing characters
+- Did-you-mean suggestions for unknown commands (Levenshtein)
+- `--help` and `--version` flag handling
+- Options, flags, and positional arguments, with optional values for options
+- Path abbreviation registry (`Ergane.paths` / `PathRegistry`): collapses registered prefixes (default `$HOME` → `~`), longest-prefix-wins and boundary-safe; commands call `abbreviate_path`
+- Interactive output helpers: `Ergane::Formatter.confirm?` and `Ergane::Formatter.time_ago`
+- Core extensions (`blank?`, `present?`, `try`, `underscore`, `demodulize`, `Array.wrap`, `Hash#&`)
+- `OptionParser#order_recognized!` for multi-level flag passthrough
+
+## [0.0.1] - 2023-05-08
 
 - Initial release

data/LICENSE

@@ -1,21 +1,22 @@
-The MIT License (MIT)
+Copyright (c) 2026 Twilight Coders, LLC
 
-Copyright (c) 2023 Dale Stevens
+MIT License
 
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
 
-The above copyright notice and this permission notice shall be included in
-all copies or substantial portions of the Software.
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
 
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
-THE SOFTWARE.
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -1,18 +1,267 @@
+<img src="https://github.com/TwilightCoders/ergane/blob/main/media/ergane.png?raw=true" alt="Athena Ergane" width="400" style="float: right"/>
+
 # Ergane
-**The patron goddess of craftsmen and artisans**
 
-Library for creating lightweight, yet powerful CLI tools in Ruby.
-Emphasis and priority on load speed and flexibility.
+[![Version](https://img.shields.io/gem/v/ergane.svg)](https://rubygems.org/gems/ergane)
+[![CI](https://github.com/TwilightCoders/ergane/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/TwilightCoders/ergane/actions/workflows/ci.yml)
+[![Code Coverage](https://qlty.sh/badges/43c39f23-168e-475f-a9fd-1754eaca83e6/coverage.svg)](https://qlty.sh/gh/TwilightCoders/projects/ergane)
+[![Maintainability](https://qlty.sh/badges/43c39f23-168e-475f-a9fd-1754eaca83e6/maintainability.svg)](https://qlty.sh/gh/TwilightCoders/projects/ergane)
+
+A lightweight, powerful CLI framework for Ruby. Define commands using class inheritance or block DSL — both produce the same command tree.
+
+An alternative to other similar utilities with a cleaner, more Ruby-native design.
+
+Named after [Athena Ergane](https://en.wikipedia.org/wiki/Athena#Ergane), patron of craftsmen and toolmakers.
 
 ## Requirements
-Ruby 2.7+
 
-May work with older versions.
+Ruby 3.1+
+
+## Installation
+
+```ruby
+gem "ergane"
+```
+
+## Quick Start
+
+```ruby
+require "ergane"
+
+class MyCLI < Ergane::Tool
+  tool_name :mycli
+  version "1.0.0"
+  description "My awesome CLI tool"
+
+  command :greet do
+    description "Say hello"
+    option :name, String, short: :n, default: "world"
+
+    run { puts "Hello #{options[:name]}!" }
+  end
+end
+
+MyCLI.start(ARGV)
+```
+
+```
+$ mycli greet -n 'Johnny Appleseed'
+Hello Johnny Appleseed!
+
+$ mycli --help
+My awesome CLI tool
+
+Version: 1.0.0
+
+Usage: mycli [options] [subcommand]
+
+Subcommands:
+  greet  Say hello
+
+$ mycli greet --help
+Say hello
+
+Usage: greet [options]
+
+Options:
+  -n, --name=VALUE  (default: world)
+```
+
+## Defining Commands
+
+Ergane supports two equivalent styles for defining commands. Both produce the same underlying `Command` subclass.
+
+### Block-based DSL
+
+Best for quick, self-contained commands:
+
+```ruby
+class MyCLI < Ergane::Tool
+  tool_name :mycli
+  version "1.0.0"
+
+  command :deploy do
+    description "Deploy the application"
+    option :env, String, short: :e, default: "staging"
+    flag :force, short: :f, description: "Skip confirmation"
+
+    run do |*targets|
+      puts "Deploying #{targets.join(', ')} to #{options[:env]}"
+      puts "Force mode!" if options[:force]
+    end
+  end
+end
+```
+
+### Class-based
+
+Best for complex commands that need helper methods, mixins, or testing in isolation.
+
+Defining a Tool automatically creates a `MyCLI::Command` base class for your commands to inherit from:
+
+```ruby
+class Deploy < MyCLI::Command
+  self.command_name = :deploy
+  description "Deploy the application"
+  option :env, String, short: :e, default: "staging"
+  flag :force, short: :f, description: "Skip confirmation"
+
+  def run(*targets)
+    puts "Deploying #{targets.join(', ')} to #{options[:env]}"
+    puts "Force mode!" if options[:force]
+  end
+
+  private
+
+  def confirm?
+    return true if options[:force]
+    # ...
+  end
+end
+```
+
+### Nested Subcommands
+
+Both styles support nesting to arbitrary depth:
+
+```ruby
+class MyCLI < Ergane::Tool
+  tool_name :mycli
+  version "1.0.0"
+
+  command :server do
+    description "Server management"
+
+    command :start do
+      description "Start the server"
+      option :port, String, short: :p, default: "3000"
+
+      run { puts "Starting on port #{options[:port]}" }
+    end
+
+    command :stop do
+      description "Stop the server"
+      run { puts "Stopping server" }
+    end
+  end
+end
+```
+
+```
+$ mycli server start -p 8080
+Starting on port 8080
+```
+
+## Options and Flags
+
+```ruby
+# Typed option (requires a value)
+option :env, String, short: :e, description: "Target environment", default: "staging"
+
+# Boolean flag (no value, defaults to false)
+flag :verbose, short: :v, description: "Enable verbose output"
+
+# Positional argument
+argument :target, description: "Deploy target"
+```
+
+Options are accessed via the `options` hash:
+
+```ruby
+run do |*args|
+  puts options[:env]      # => "staging"
+  puts options[:verbose]  # => false
+end
+```
+
+## Loading Commands from Files
+
+For larger CLIs, organize commands in separate files:
+
+```ruby
+class MyCLI < Ergane::Tool
+  tool_name :mycli
+  version "1.0.0"
+
+  load_commands(File.expand_path("commands/**/*.rb", __dir__))
+end
+```
+
+Each file defines a Command subclass that auto-registers via Ruby's `inherited` hook:
+
+```ruby
+# commands/deploy.rb
+class Deploy < MyCLI::Command
+  self.command_name = :deploy
+  description "Deploy the application"
+
+  def run(*targets)
+    # ...
+  end
+end
+```
+
+## Custom Command Base
+
+For shared behavior across all commands, provide your own base class:
+
+```ruby
+class MyBaseCommand < Ergane::Command
+  self.abstract_class = true
+  flag :verbose, short: :v, description: "Verbose output"
+
+  def log(msg)
+    puts msg if options[:verbose]
+  end
+end
+
+class MyCLI < Ergane::Tool
+  tool_name :mycli
+  version "1.0.0"
+  command_class MyBaseCommand
+end
+
+class Deploy < MyBaseCommand
+  self.command_name = :deploy
+  description "Deploy the application"
+
+  def run(*targets)
+    log "Deploying #{targets.join(', ')}"
+  end
+end
+```
+
+## Abstract Commands
+
+Group related commands with shared options:
+
+```ruby
+class DatabaseCommand < MyCLI::Command
+  self.abstract_class = true
+  option :database, String, short: :d, default: "primary"
+end
+
+class Migrate < DatabaseCommand
+  self.command_name = :migrate
+  description "Run migrations"
+
+  def run
+    puts "Migrating #{options[:database]}"
+  end
+end
+```
+
+## Development
+
+After checking out the repo, run `bundle` to install dependencies. Then, run `bundle exec rspec` to run the tests.
 
 ## Contributing
 
-1. Fork it ( https://github.com/TwilightCoders/ergane/fork )
-2. Create your feature branch (`git checkout -b my-new-feature`)
-3. Commit your changes (`git commit -am 'Add some feature'`)
-4. Push to the branch (`git push origin my-new-feature`)
-5. Create a new Pull Request
+Bug reports and pull requests are welcome on GitHub at
+<https://github.com/TwilightCoders/ergane>. This project is intended to be a safe,
+welcoming space for collaboration, and contributors are expected to adhere to the
+[Contributor Covenant](http://contributor-covenant.org) code of conduct.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).

data/lib/ergane/argument_definition.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Ergane
+  class ArgumentDefinition
+    attr_reader :name, :type, :description, :required, :default
+
+    def initialize(name, type = String, description: nil, required: true, default: nil)
+      @name = name.to_sym
+      @type = type
+      @description = description
+      @required = required
+      @default = default
+    end
+  end
+end

data/lib/ergane/command.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+module Ergane
+  class Command
+    include Concerns::Inheritance
+    include Concerns::OptionHandling
+    extend DSL::CommandDSL
+
+    self.abstract_class = true
+
+    class << self
+      def command_name=(name)
+        @command_name = name&.to_sym
+        return unless @command_name
+
+        parent = superclass
+        if parent.respond_to?(:tool) && parent.abstract_class?
+          parent.inherited_command_name_set(self)
+        else
+          register_subcommand(self)
+        end
+      end
+
+      def command_name
+        @command_name || derive_command_name
+      end
+
+      def terms
+        [command_name, *aliases].compact.uniq
+      end
+
+      def subcommands
+        @subcommands ||= {}
+      end
+
+      def inherited(subclass)
+        super
+        subclass.instance_variable_set(:@option_definitions, option_definitions.dup)
+        subclass.instance_variable_set(:@argument_definitions, argument_definitions.dup)
+        subclass.instance_variable_set(:@subcommands, {})
+        register_subcommand(subclass)
+      end
+
+      private
+
+      def derive_command_name
+        return nil if self == Command || abstract_class?
+        base = name&.demodulize
+        return nil unless base
+        base.sub(/Command$/, "").underscore.to_sym
+      end
+
+      def register_subcommand(subclass)
+        parent = subclass.superclass
+        return if parent == Command || parent.abstract_class?
+        cmd_name = subclass.command_name
+        return unless cmd_name
+        parent.subcommands[cmd_name] = subclass
+      end
+    end
+
+    attr_reader :options
+
+    def abbreviate_path(path)
+      Ergane.paths.abbreviate(path)
+    end
+
+    def initialize(argv = [])
+      @options = self.class.build_default_options
+      @argv = parse_options(argv.dup)
+    end
+
+    def args
+      @argv
+    end
+
+    def run(*run_args)
+      if self.class.subcommands.any?
+        $stdout.puts HelpFormatter.new(self.class).format
+      else
+        raise AbstractCommand, "#{self.class.name}#run is not implemented"
+      end
+    end
+  end
+end

data/lib/ergane/concerns/inheritance.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module Ergane
+  module Concerns
+    module Inheritance
+      def self.included(base)
+        base.extend(ClassMethods)
+      end
+
+      module ClassMethods
+        def abstract_class=(value)
+          @abstract_class = value
+          # Unregister from parent's subcommands when marked abstract
+          if value && respond_to?(:command_name) && self < Ergane::Command
+            parent = superclass
+            parent.subcommands.delete(command_name) if parent.respond_to?(:subcommands)
+          end
+        end
+
+        def abstract_class?
+          @abstract_class == true
+        end
+
+        # Returns the class descending directly from Ergane::Command, or
+        # an abstract class, if any, in the inheritance hierarchy.
+        #
+        # If A extends Command, A.base_class returns A.
+        # If B < A through some hierarchy, B.base_class returns A.
+        # If A is abstract, both B.base_class and C.base_class return B.
+        def base_class
+          unless self < Ergane::Command
+            raise Ergane::Error, "#{name} doesn't belong in a hierarchy descending from Ergane::Command"
+          end
+
+          if superclass == Ergane::Command || superclass.abstract_class?
+            self
+          else
+            superclass.base_class
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ergane/concerns/option_handling.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Ergane
+  module Concerns
+    module OptionHandling
+      def self.included(base)
+        base.extend(ClassMethods)
+      end
+
+      module ClassMethods
+        def option_definitions
+          @option_definitions ||= {}
+        end
+
+        def argument_definitions
+          @argument_definitions ||= []
+        end
+
+        def build_default_options
+          option_definitions.each_with_object({}) do |(name, defn), hash|
+            hash[name] = defn.default_value
+          end
+        end
+
+        def build_option_parser(store)
+          ::OptionParser.new do |parser|
+            option_definitions.each_value do |defn|
+              defn.attach(parser, store)
+            end
+          end
+        end
+      end
+
+      private
+
+      def parse_options(argv)
+        parser = self.class.build_option_parser(@options)
+        parser.order_recognized!(argv)
+        argv
+      end
+    end
+  end
+end

data/lib/ergane/core_ext/array.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+class Array
+  def self.wrap(object)
+    if object.nil?
+      []
+    elsif object.respond_to?(:to_ary)
+      object.to_ary || [object]
+    else
+      [object]
+    end
+  end unless respond_to?(:wrap)
+end

data/lib/ergane/core_ext/hash.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+class Hash
+  # Hash intersection by keys. Values come from the receiver.
+  #   {a: 1, b: 2} & {a: 10, c: 3}  # => {a: 1}
+  def &(other)
+    shared = keys & other.keys
+    shared.each_with_object({}) { |k, h| h[k] = self[k] }
+  end unless method_defined?(:&)
+end

data/lib/ergane/core_ext/object.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+class Object
+  def blank?
+    respond_to?(:empty?) ? !!empty? : !self
+  end unless method_defined?(:blank?)
+
+  def present?
+    !blank?
+  end unless method_defined?(:present?)
+
+  def try(method_name = nil, *args, &block)
+    if method_name
+      respond_to?(method_name) ? public_send(method_name, *args, &block) : nil
+    elsif block
+      yield self
+    end
+  end unless method_defined?(:try)
+end
+
+class NilClass
+  def blank? = true unless method_defined?(:blank?)
+  def try(*) = nil unless method_defined?(:try)
+end
+
+class FalseClass
+  def blank? = true unless method_defined?(:blank?)
+end
+
+class TrueClass
+  def blank? = false unless method_defined?(:blank?)
+end
+
+class String
+  # Override Object#blank? to also catch whitespace-only strings
+  def blank?
+    empty? || /\A[[:space:]]*\z/.match?(self)
+  end
+end
+
+class Numeric
+  def blank? = false unless method_defined?(:blank?)
+end

data/lib/{core_ext → ergane/core_ext}/option_parser.rb

@@ -1,6 +1,8 @@
-class OptionParser
+# frozen_string_literal: true
 
+class OptionParser
   # Like order!, but leave any unrecognized --switches alone
+  # instead of raising InvalidOption.
   def order_recognized!(args)
     extra_opts = []
     begin
@@ -11,5 +13,4 @@ class OptionParser
     end
     args[0, 0] = extra_opts
   end
-
 end

data/lib/ergane/core_ext/string.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+class String
+  # "DeployCommand" -> "deploy_command"
+  # "Ergane::Deploy" -> "ergane/deploy"
+  def underscore
+    gsub("::", "/")
+      .gsub(/([A-Z]+)([A-Z][a-z])/, '\1_\2')
+      .gsub(/([a-z\d])([A-Z])/, '\1_\2')
+      .tr("-", "_")
+      .downcase
+  end unless method_defined?(:underscore)
+
+  # "Ergane::Deploy" -> "Deploy"
+  def demodulize
+    if (index = rindex("::"))
+      self[(index + 2)..]
+    else
+      dup
+    end
+  end unless method_defined?(:demodulize)
+end

data/lib/ergane/dsl/block_dsl.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Ergane
+  module DSL
+    class BlockDSL
+      def initialize(command_class)
+        @command_class = command_class
+      end
+
+      def run(&block)
+        @command_class.define_method(:run) { |*args| instance_exec(*args, &block) }
+      end
+
+      private
+
+      def respond_to_missing?(name, include_private = false)
+        @command_class.respond_to?(name) || super
+      end
+
+      def method_missing(name, *args, **opts, &block)
+        if @command_class.respond_to?(name)
+          @command_class.public_send(name, *args, **opts, &block)
+        else
+          super
+        end
+      end
+    end
+  end
+end