ergane 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 53b7a242e903c28ff9ddb5f33ee399c044fd618f0420cd3868cecb02c4e277e6
-  data.tar.gz: 9f8e7b16cc0f64f3547b98e41d973f4b90528215e516873600eb6e953bd2141a
+  metadata.gz: 5bac11b2362d538571dc708483d4cbc83ee2a66e51983c5e9c312e5a1a98d3f3
+  data.tar.gz: e27be5089a4034d7a67d26b17f4b5572d723a6ed38f3c29275d2089d6ead65cd
 SHA512:
-  metadata.gz: fdcf833f1190263dc9f37f470c03d7d150e566175d927e2fec39c036a22111fca8b59c7af4d64a1c1c66af1a455eecb257f66cf2c5276f0f672a513eda123e9a
-  data.tar.gz: c85a0eb19d99c6c5424e40655a6c64f33591e04a0d11d576076e2e9a03d2e9ed4f8b26080c21b052145fdff3097e4bd01687226e31abaf84f77013e155954dd9
+  metadata.gz: e136d486d292c5bac857f0cd8a950189d562aef43f76320b65c672bcc11f98af37658cac4b201a607c8ba103f73d84a94b5bfeafefa4044ccbd98a62707240ad
+  data.tar.gz: c36af86e50cb12b0cdd270744cea2f4c3a3f88570c8bd305bcd976f8466ffa8e6d34a827df3619b317b2c86fcc30d73fbcecc4b10d7a9b4eed250d028baf9913

data/CHANGELOG.md

@@ -2,6 +2,26 @@
 
 ## [Unreleased]
 
+## [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

data/README.md

@@ -174,6 +174,18 @@ run do |*args|
 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:

data/lib/ergane/argument_definition.rb

@@ -4,7 +4,9 @@ module Ergane
   class ArgumentDefinition
     attr_reader :name, :type, :description, :required, :default
 
-    def initialize(name, type = String, description: nil, required: true, default: nil)
+    # +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

data/lib/ergane/command.rb

@@ -11,14 +11,7 @@ module Ergane
     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
+        register!
       end
 
       def command_name
@@ -33,16 +26,36 @@ module Ergane
         @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, {})
-        register_subcommand(subclass)
+        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
@@ -50,12 +63,36 @@ module Ergane
         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
+      # 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
 
@@ -67,7 +104,7 @@ module Ergane
 
     def initialize(argv = [])
       @options = self.class.build_default_options
-      @argv = parse_options(argv.dup)
+      @argv = process_arguments(parse_options(argv.dup))
     end
 
     def args
@@ -81,5 +118,42 @@ module Ergane
         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

@@ -10,11 +10,9 @@ module Ergane
       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
+          # 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?

data/lib/ergane/core_ext/object.rb

@@ -32,10 +32,14 @@ class TrueClass
 end
 
 class String
-  # Override Object#blank? to also catch whitespace-only strings
+  # Catch whitespace-only strings, overriding the inherited Object#blank?.
+  # Guarded on String's OWN methods — not method_defined?, which would see the
+  # inherited Object#blank? and skip, leaving the whitespace-blind version. This
+  # still defines our version normally, but yields to any external String#blank?
+  # (e.g. ActiveSupport) rather than clobbering it.
   def blank?
     empty? || /\A[[:space:]]*\z/.match?(self)
-  end
+  end unless instance_methods(false).include?(:blank?)
 end
 
 class Numeric

data/lib/ergane/core_ext/option_parser.rb

@@ -4,13 +4,15 @@ class OptionParser
   # Like order!, but leave any unrecognized --switches alone
   # instead of raising InvalidOption.
   def order_recognized!(args)
-    extra_opts = []
-    begin
-      order!(args) { |a| extra_opts << a }
-    rescue OptionParser::InvalidOption => e
-      extra_opts << e.args[0]
-      retry
+    leftover = []
+    until args.empty?
+      begin
+        order!(args) { |nonopt| leftover << nonopt }
+        break
+      rescue OptionParser::InvalidOption => e
+        leftover.concat(e.args)
+      end
     end
-    args[0, 0] = extra_opts
+    args.replace(leftover)
   end
 end

data/lib/ergane/dsl/command_dsl.rb

@@ -3,9 +3,9 @@
 module Ergane
   module DSL
     module CommandDSL
-      def description(text = nil)
-        text ? (@description = text) : (@description || "")
-      end
+      extend Macros
+
+      dsl_value :description, default: ""
 
       def aliases(*names)
         names.any? ? (@aliases = names.flatten.map(&:to_sym)) : (@aliases || [])
@@ -22,7 +22,7 @@ module Ergane
         option(name, nil, short: short, description: description, default: false)
       end
 
-      def argument(name, type = String, description: nil, required: true, default: nil)
+      def argument(name, type = String, description: nil, required: nil, default: nil)
         argument_definitions << ArgumentDefinition.new(
           name, type, description: description, required: required, default: default
         )

data/lib/ergane/dsl/macros.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Ergane
+  module DSL
+    # Helpers for defining DSL methods on a host class/module.
+    module Macros
+      # Defines a class-level "value" accessor with combined getter/setter
+      # semantics: called with a truthy argument it stores and returns it;
+      # called with none (or a falsy value) it returns the stored value, or
+      # +default+ if unset.
+      #
+      #   dsl_value :description, default: ""
+      #   description "Deploy"   # => "Deploy" (and stored)
+      #   description            # => "Deploy"
+      def dsl_value(name, default: nil)
+        ivar = "@#{name}"
+        define_method(name) do |value = nil|
+          value ? instance_variable_set(ivar, value) : (instance_variable_get(ivar) || default)
+        end
+      end
+    end
+  end
+end

data/lib/ergane/help_formatter.rb

@@ -37,8 +37,8 @@ module Ergane
       usage = path.light_red
       usage += " [options]".light_cyan if command_class.option_definitions.any?
       usage += " [subcommand]".light_black.underline if command_class.subcommands.any?
-      command_class.argument_definitions.each do |arg|
-        label = arg.required ? "<#{arg.name}>" : "[#{arg.name}]"
+      command_class.argument_definitions.each_with_index do |arg, i|
+        label = command_class.argument_required?(i) ? "<#{arg.name}>" : "[#{arg.name}]"
         usage += " #{label}".light_yellow
       end
       "Usage:".light_cyan + " " + usage
@@ -49,21 +49,18 @@ module Ergane
       return if subs.empty?
 
       max_width = subs.keys.map { |k| k.to_s.length }.max
-      Util::Formatting.reset_colors!
-
-      lines = []
-      lines << "Subcommands:".light_cyan
-      header_len = lines.last.uncolorize.length
-      lines << ("  \u250C" + ("\u2500" * (header_len - 2)) + "\u2518").light_black
+      colors = Util::Formatting::COLORS.cycle
+      title = "Subcommands"
 
+      lines = [("  \u250C" + ("\u2500" * (title.length - 1)) + "\u2518").light_black]
       subs.each do |name, sub_class|
         label = name.to_s.ljust(max_width + 2)
         desc = sub_class.description.present? ? sub_class.description.light_black : ""
-        lines << "  \u251C\u2500\u2510".light_black + " #{label.send(Util::Formatting.next_color)} #{desc}"
+        lines << "  \u251C\u2500\u2510".light_black + " #{label.send(colors.next)} #{desc}"
       end
-
       lines << ("  \u2514" + "\u2500" * 40).light_black
-      lines.join("\n")
+
+      section(title, lines)
     end
 
     def options_section
@@ -72,14 +69,13 @@ module Ergane
 
       max_width = opts.values.map { |o| o.signature.length }.max
 
-      lines = ["Options:".light_cyan]
-      opts.each_value do |opt|
+      lines = opts.each_value.map do |opt|
         sig = opt.signature.ljust(max_width + 2)
         desc = opt.description || ""
         default_note = opt.default_value ? " (default: #{opt.default_value})".light_black : ""
-        lines << "  #{sig.light_green} #{desc}#{default_note}"
+        "  #{sig.light_green} #{desc}#{default_note}"
       end
-      lines.join("\n")
+      section("Options", lines)
     end
 
     def arguments_section
@@ -88,14 +84,21 @@ module Ergane
 
       max_width = args.map { |a| a.name.to_s.length }.max
 
-      lines = ["Arguments:".light_cyan]
-      args.each do |arg|
+      lines = args.each_with_index.map do |arg, i|
         label = arg.name.to_s.ljust(max_width + 2)
         desc = arg.description || ""
-        req = arg.required ? " (required)".light_red : " (optional)".light_black
-        lines << "  #{label.light_yellow} #{desc}#{req}"
+        req = command_class.argument_required?(i) ? " (required)".light_red : " (optional)".light_black
+        "  #{label.light_yellow} #{desc}#{req}"
       end
-      lines.join("\n")
+      section("Arguments", lines)
+    end
+
+    # Renders a titled block: a cyan "Title:" header followed by its lines,
+    # or nil when there are no lines (so #format compacts it away).
+    def section(title, lines)
+      return if lines.empty?
+
+      ["#{title}:".light_cyan, *lines].join("\n")
     end
   end
 end

data/lib/ergane/path_registry.rb

@@ -32,16 +32,19 @@ module Ergane
       self
     end
 
-    # Collapse the longest matching prefix in +path+ to its label,
-    # returning the path unchanged when nothing matches.
+    # Collapse the longest matching prefix in +path+ to its label, returning
+    # the path unchanged when nothing matches. The input is expanded before
+    # matching (mirroring how prefixes are stored on #register), so matching
+    # is consistent across platforms and "~"-relative input is accepted.
     def abbreviate(path)
-      str = path.to_s
+      original = path.to_s
+      expanded = File.expand_path(original)
       best = @substitutions
-        .select { |sub| str == sub.prefix || str.start_with?("#{sub.prefix}/") }
+        .select { |sub| expanded == sub.prefix || expanded.start_with?("#{sub.prefix}/") }
         .max_by { |sub| sub.prefix.length }
-      return str unless best
+      return original unless best
 
-      "#{best.label}#{str[best.prefix.length..]}"
+      "#{best.label}#{expanded[best.prefix.length..]}"
     end
   end
 end

data/lib/ergane/runner.rb

@@ -47,6 +47,10 @@ module Ergane
       if sub
         args.shift
         resolve(sub, args, path)
+      elsif command_class.subcommands.any?
+        # The current command is a group, so an unmatched token is a bad
+        # subcommand — not a positional arg for a leaf command.
+        raise CommandNotFound.new(token, available: command_class.subcommands.keys)
       else
         [command_class, args, path]
       end

data/lib/ergane/tool.rb

@@ -5,6 +5,10 @@ module Ergane
     self.abstract_class = true
 
     class << self
+      extend DSL::Macros
+
+      dsl_value :version
+
       def command_class(klass = nil)
         if klass
           @command_class = klass
@@ -18,10 +22,6 @@ module Ergane
         name ? (self.command_name = name) : command_name
       end
 
-      def version(ver = nil)
-        ver ? (@version = ver) : @version
-      end
-
       def start(argv = ARGV)
         Runner.new(self, argv.dup).execute
       rescue Interrupt
@@ -58,27 +58,12 @@ module Ergane
         tool_subclass.command_class(base)
       end
 
+      # Gives the tool's command base (and everything below it) a reference
+      # back to the tool, so Command#registration_target can route
+      # subcommands to the tool's registry.
       def wire_command_class(klass)
         tool = self
         klass.define_singleton_method(:tool) { tool }
-
-        klass.define_singleton_method(:inherited) do |subclass|
-          super(subclass)
-          cmd_name = subclass.command_name
-          if cmd_name && !subclass.abstract_class? && subclass.superclass.abstract_class?
-            subclass.instance_variable_set(:@_derived_name, cmd_name)
-            tool.subcommands[cmd_name] = subclass
-          end
-        end
-
-        klass.define_singleton_method(:inherited_command_name_set) do |subclass|
-          cmd_name = subclass.command_name
-          if cmd_name && !subclass.abstract_class? && subclass.superclass.abstract_class?
-            derived = subclass.instance_variable_get(:@_derived_name)
-            tool.subcommands.delete(derived) if derived && derived != cmd_name
-            tool.subcommands[cmd_name] = subclass
-          end
-        end
       end
     end
   end

data/lib/ergane/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Ergane
-  VERSION = "0.1.0"
+  VERSION = "0.2.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ergane
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Dale Stevens
@@ -160,6 +160,7 @@ files:
 - lib/ergane/core_ext/string.rb
 - lib/ergane/dsl/block_dsl.rb
 - lib/ergane/dsl/command_dsl.rb
+- lib/ergane/dsl/macros.rb
 - lib/ergane/errors.rb
 - lib/ergane/formatter.rb
 - lib/ergane/help_formatter.rb
@@ -167,7 +168,6 @@ files:
 - lib/ergane/path_registry.rb
 - lib/ergane/runner.rb
 - lib/ergane/tool.rb
-- lib/ergane/util/debug.rb
 - lib/ergane/util/formatting.rb
 - lib/ergane/version.rb
 homepage: https://github.com/TwilightCoders/ergane
@@ -175,7 +175,6 @@ licenses:
 - MIT
 metadata:
   rubygems_mfa_required: 'true'
-  homepage_uri: https://github.com/TwilightCoders/ergane
   source_code_uri: https://github.com/TwilightCoders/ergane
   changelog_uri: https://github.com/TwilightCoders/ergane/blob/main/CHANGELOG.md
 rdoc_options: []

data/lib/ergane/util/debug.rb

@@ -1,24 +0,0 @@
-# frozen_string_literal: true
-
-module Ergane
-  module Util
-    module Debug
-      def self.enabled?
-        !!$ergane_debug
-      end
-
-      def self.enable!
-        $ergane_debug = true
-      end
-
-      def self.disable!
-        $ergane_debug = false
-      end
-
-      def self.log(message)
-        return unless enabled?
-        $stderr.puts "[Ergane DEBUG] #{message}"
-      end
-    end
-  end
-end