ergane 0.0.1 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6f27bb356ea374b87bf0a12ad73bc945e518dee66aa18797b5f9b06a197de896
-  data.tar.gz: 2de58095dd7014c321d13fcac71f9d16019db72cd6feb0896bafea5f9ae19d6e
+  metadata.gz: 5bac11b2362d538571dc708483d4cbc83ee2a66e51983c5e9c312e5a1a98d3f3
+  data.tar.gz: e27be5089a4034d7a67d26b17f4b5572d723a6ed38f3c29275d2089d6ead65cd
 SHA512:
-  metadata.gz: 3a3431e9dd63b745dc3765a83c98c0d3ed3d60837373d12b69371f1df05e5718be8b2fd5007808e4383ba8d77c0fd6997ba7dc867e317b5b598fc80921429161
-  data.tar.gz: fa7972b5a4019cff455ca2f0631181cb3ce49192a56ee01eb549c22827fbc8d41b77cc86d089178d04e2b63474626faab18dd3acbe45be12aedaec5a37254955
+  metadata.gz: e136d486d292c5bac857f0cd8a950189d562aef43f76320b65c672bcc11f98af37658cac4b201a607c8ba103f73d84a94b5bfeafefa4044ccbd98a62707240ad
+  data.tar.gz: c36af86e50cb12b0cdd270744cea2f4c3a3f88570c8bd305bcd976f8466ffa8e6d34a827df3619b317b2c86fcc30d73fbcecc4b10d7a9b4eed250d028baf9913

data/CHANGELOG.md

@@ -1,5 +1,48 @@
+# CHANGELOG
+
 ## [Unreleased]
 
-## [0.1.0] - 2023-04-26
+## [0.2.0] - 2026-05-25
+
+### Changed
+- **Unknown subcommands on a command group now raise `CommandNotFound`** (with a did-you-mean suggestion) and exit non-zero, instead of silently printing help. Scoped to command groups — leaf commands still treat unmatched tokens as positional arguments.
+- **Positional `argument` declarations are now enforced.** Required-ness is derived from the command's `run` signature — a required parameter (`run(name)`) makes the argument required, while an optional one (`run(name = nil)`) or a splat (`run(*)`) makes it optional; an explicit `required:` on the `argument` overrides the signature. A missing required argument raises `MissingArgument`; an absent optional argument takes its `default:`; values are coerced to the declared `type:` (`String` is identity, `Integer`/`Float` via Kernel conversion raising `InvalidOption` on bad input). Previously these keywords affected only help text.
+
+### Added
+- `Ergane::DSL::Macros.dsl_value` — a class-level getter/setter accessor generator used by the DSL.
+
+### Fixed
+- `PathRegistry#abbreviate` now expands its input before matching (mirroring `#register`), so abbreviation is consistent across platforms (notably Windows, where un-expanded inputs failed to match drive-qualified prefixes) and accepts `~`-relative input.
+- `OptionParser#order_recognized!` no longer drops the trailing tokens of a multi-token unknown option, and preserves argument order.
+- `String#blank?` is guarded against external definitions (e.g. ActiveSupport) instead of unconditionally overriding them.
+- Tool-rooted abstract intermediate commands are no longer stranded in the tool's registry when marked abstract.
+
+### Internal
+- Command registration unified into a single `register!` path (removed the duplicate `define_singleton_method`'d `inherited`/`inherited_command_name_set` hooks).
+- `HelpFormatter` renders through a shared `section` helper with a per-render color cycler (no module-level mutable state).
+- `Util::Debug` is no longer packaged in the gem (dev-only tooling).
+
+## [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,279 @@
+<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
+```
+
+### Positional Arguments
+
+An argument's required-ness is derived from the command's `run` signature — a required parameter makes it required, while an optional parameter or a splat makes it optional:
+
+```ruby
+def run(source, destination = nil, *rest)
+  # source is required; destination is optional
+end
+```
+
+Pass `required:` on the `argument` to override the signature, `type:` to coerce the value (a non-`String` type is converted, raising on failure), and `default:` for an absent optional argument. A missing required argument raises `Ergane::MissingArgument`.
+
+## 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,17 @@
+# frozen_string_literal: true
+
+module Ergane
+  class ArgumentDefinition
+    attr_reader :name, :type, :description, :required, :default
+
+    # +required+ defaults to nil, meaning "derive from the run signature";
+    # pass true/false to force it.
+    def initialize(name, type = String, description: nil, required: nil, 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,159 @@
+# 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
+        register!
+      end
+
+      def command_name
+        @command_name || derive_command_name
+      end
+
+      def terms
+        [command_name, *aliases].compact.uniq
+      end
+
+      def subcommands
+        @subcommands ||= {}
+      end
+
+      # Effective required-ness of the positional argument at +index+. An
+      # explicit DSL `required:` (true/false) wins; otherwise it's derived from
+      # the run method's matching positional parameter: a required parameter
+      # (`run(name)`) means required, while an optional one (`run(name = nil)`)
+      # or a splat (`run(*)`) means optional.
+      def argument_required?(index)
+        defn = argument_definitions[index]
+        return false unless defn
+        return defn.required unless defn.required.nil?
+
+        param = run_positional_parameters[index]
+        param ? param.first == :req : false
+      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, {})
+        subclass.send(:register!)
+      end
+
+      private
+
+      # The run method's positional parameters (required/optional), in order,
+      # which line up with declared arguments. Excludes splat/keyword params.
+      def run_positional_parameters
+        instance_method(:run).parameters.select { |kind, _| kind == :req || kind == :opt }
+      end
+
+      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
+
+      # The registry this command belongs in: a tool's abstract command base
+      # registers under the tool itself; a concrete parent registers under
+      # that parent. A command rooted directly on Command, or under an
+      # abstract non-tool parent, registers nowhere.
+      def registration_target
+        parent = superclass
+        if parent.respond_to?(:tool) && parent.abstract_class?
+          parent.tool
+        elsif parent != Command && !parent.abstract_class?
+          parent
+        end
+      end
+
+      # Registers (or re-registers) this command in its target registry under
+      # its current command_name, removing any prior registration when the
+      # name changes or the command becomes abstract. Idempotent — safe to
+      # call from both .inherited and command_name=.
+      def register!
+        target = registration_target
+        return unless target
+
+        name = abstract_class? ? nil : command_name
+
+        target.subcommands.delete(@registered_as) if @registered_as && @registered_as != name
+        if name
+          target.subcommands[name] = self
+          @registered_as = name
+        else
+          @registered_as = nil
+        end
+      end
+    end
+
+    attr_reader :options
+
+    def abbreviate_path(path)
+      Ergane.paths.abbreviate(path)
+    end
+
+    def initialize(argv = [])
+      @options = self.class.build_default_options
+      @argv = process_arguments(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
+
+    private
+
+    # Validates and coerces positional args against the command's argument
+    # definitions: missing required args raise, absent optional args take
+    # their default, and present args are coerced by type. Extra positionals
+    # beyond the declared arguments pass through untouched (e.g. for run(*)).
+    def process_arguments(argv)
+      definitions = self.class.argument_definitions
+      return argv if definitions.empty?
+
+      declared = definitions.each_with_index.map do |defn, i|
+        if i < argv.length
+          coerce_argument(argv[i], defn)
+        elsif self.class.argument_required?(i)
+          raise MissingArgument, "Missing required argument: <#{defn.name}>"
+        else
+          defn.default
+        end
+      end
+      declared + argv.drop(definitions.length)
+    end
+
+    def coerce_argument(value, defn)
+      type = defn.type
+      return value if type.nil? || type == String
+
+      if type == Integer
+        Integer(value)
+      elsif type == Float
+        Float(value)
+      else
+        value
+      end
+    rescue ArgumentError
+      raise InvalidOption, "Invalid value for <#{defn.name}>: #{value.inspect} (expected #{type})"
+    end
+  end
+end

data/lib/ergane/concerns/inheritance.rb

@@ -0,0 +1,42 @@
+# 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
+          # Re-run registration so the command leaves (or rejoins) its
+          # registry to match its new abstract state.
+          register! if self < Ergane::Command && respond_to?(:register!, true)
+        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