ergane 0.0.1 → 0.2.0

data/lib/ergane/core_ext/object.rb

@@ -0,0 +1,47 @@
+# 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
+  # 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 unless instance_methods(false).include?(:blank?)
+end
+
+class Numeric
+  def blank? = false unless method_defined?(:blank?)
+end

data/lib/ergane/core_ext/option_parser.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+class OptionParser
+  # Like order!, but leave any unrecognized --switches alone
+  # instead of raising InvalidOption.
+  def order_recognized!(args)
+    leftover = []
+    until args.empty?
+      begin
+        order!(args) { |nonopt| leftover << nonopt }
+        break
+      rescue OptionParser::InvalidOption => e
+        leftover.concat(e.args)
+      end
+    end
+    args.replace(leftover)
+  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

data/lib/ergane/dsl/command_dsl.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Ergane
+  module DSL
+    module CommandDSL
+      extend Macros
+
+      dsl_value :description, default: ""
+
+      def aliases(*names)
+        names.any? ? (@aliases = names.flatten.map(&:to_sym)) : (@aliases || [])
+      end
+
+      def option(name, type = nil, short: nil, description: nil, default: nil, required: false, optional: false)
+        option_definitions[name.to_sym] = OptionDefinition.new(
+          name, type, short: short, description: description,
+          default: default, required: required, optional: optional
+        )
+      end
+
+      def flag(name, short: nil, description: nil)
+        option(name, nil, short: short, description: description, default: false)
+      end
+
+      def argument(name, type = String, description: nil, required: nil, default: nil)
+        argument_definitions << ArgumentDefinition.new(
+          name, type, description: description, required: required, default: default
+        )
+      end
+
+      def command(name, aliases: [], &block)
+        klass = Class.new(command_base_for(name))
+        klass.command_name = name.to_sym
+        klass.aliases(*aliases) if aliases.any?
+
+        const_name = name.to_s.split("_").map(&:capitalize).join
+        const_set(const_name, klass) if const_name.match?(/\A[A-Z]/)
+
+        BlockDSL.new(klass).instance_eval(&block) if block
+        klass
+      end
+
+      private
+
+      def command_base_for(_name)
+        self
+      end
+    end
+  end
+end

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/errors.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Ergane
+  class Error < StandardError; end
+
+  class CommandNotFound < Error
+    attr_reader :token, :available
+
+    def initialize(token, available: [])
+      @token = token
+      @available = available
+      suggestion = find_suggestion
+      msg = "Unknown command: '#{token}'"
+      msg += ". Did you mean '#{suggestion}'?" if suggestion
+      msg += "\nAvailable commands: #{available.join(', ')}" if available.any?
+      super(msg)
+    end
+
+    private
+
+    def find_suggestion
+      return nil if available.empty?
+      best = available.min_by { |cmd| levenshtein(token.to_s, cmd.to_s) }
+      dist = levenshtein(token.to_s, best.to_s)
+      dist <= [token.to_s.length / 2, 3].max ? best : nil
+    end
+
+    def levenshtein(a, b)
+      m, n = a.length, b.length
+      return n if m.zero?
+      return m if n.zero?
+
+      d = Array.new(m + 1) { |i| i }
+      (1..n).each do |j|
+        prev = d[0]
+        d[0] = j
+        (1..m).each do |i|
+          cost = a[i - 1] == b[j - 1] ? 0 : 1
+          temp = d[i]
+          d[i] = [d[i] + 1, d[i - 1] + 1, prev + cost].min
+          prev = temp
+        end
+      end
+      d[m]
+    end
+  end
+
+  class MissingArgument < Error; end
+  class InvalidOption < Error; end
+  class AbstractCommand < Error; end
+end

data/lib/ergane/formatter.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Ergane
+  # Small, generic output helpers for interactive CLIs.
+  module Formatter
+    class << self
+      # Prompt on stderr and return true only for an affirmative answer.
+      # Returns false when stdin isn't a TTY (non-interactive / piped input).
+      def confirm?(prompt)
+        $stderr.print "#{prompt} [y/N] "
+        return false unless $stdin.tty?
+
+        answer = $stdin.gets&.strip
+        answer&.match?(/\Ay(es)?\z/i)
+      end
+
+      # Humanize the distance from +time+ to now: "just now", "5m ago",
+      # "3h ago", "2d ago".
+      def time_ago(time)
+        seconds = (Time.now - time).to_i
+        return 'just now' if seconds < 60
+        return "#{seconds / 60}m ago" if seconds < 3600
+        return "#{seconds / 3600}h ago" if seconds < 86400
+
+        "#{seconds / 86400}d ago"
+      end
+    end
+  end
+end

data/lib/ergane/help_formatter.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+module Ergane
+  class HelpFormatter
+    attr_reader :command_class, :command_path
+
+    def initialize(command_class, command_path: [])
+      @command_class = command_class
+      @command_path = command_path
+    end
+
+    def format
+      [
+        description_section,
+        version_section,
+        usage_section,
+        subcommands_section,
+        options_section,
+        arguments_section
+      ].compact.join("\n\n") + "\n"
+    end
+
+    private
+
+    def description_section
+      desc = command_class.description
+      desc if desc.present?
+    end
+
+    def version_section
+      ver = command_class.respond_to?(:version) && command_class.version
+      "Version: #{ver.to_s.light_blue}" if ver
+    end
+
+    def usage_section
+      path = command_path.any? ? command_path.join(" ") : command_class.command_name.to_s
+      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_with_index do |arg, i|
+        label = command_class.argument_required?(i) ? "<#{arg.name}>" : "[#{arg.name}]"
+        usage += " #{label}".light_yellow
+      end
+      "Usage:".light_cyan + " " + usage
+    end
+
+    def subcommands_section
+      subs = command_class.subcommands
+      return if subs.empty?
+
+      max_width = subs.keys.map { |k| k.to_s.length }.max
+      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(colors.next)} #{desc}"
+      end
+      lines << ("  \u2514" + "\u2500" * 40).light_black
+
+      section(title, lines)
+    end
+
+    def options_section
+      opts = command_class.option_definitions
+      return if opts.empty?
+
+      max_width = opts.values.map { |o| o.signature.length }.max
+
+      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 : ""
+        "  #{sig.light_green} #{desc}#{default_note}"
+      end
+      section("Options", lines)
+    end
+
+    def arguments_section
+      args = command_class.argument_definitions
+      return if args.empty?
+
+      max_width = args.map { |a| a.name.to_s.length }.max
+
+      lines = args.each_with_index.map do |arg, i|
+        label = arg.name.to_s.ljust(max_width + 2)
+        desc = arg.description || ""
+        req = command_class.argument_required?(i) ? " (required)".light_red : " (optional)".light_black
+        "  #{label.light_yellow} #{desc}#{req}"
+      end
+      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/option_definition.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module Ergane
+  class OptionDefinition
+    attr_reader :name, :type, :short, :description, :default, :required, :optional
+
+    def initialize(name, type = nil, short: nil, description: nil, default: nil, required: false, optional: false)
+      @name = name.to_sym
+      @type = type
+      @short = short&.to_s
+      @description = description
+      @default = default
+      @required = required
+      @optional = optional
+    end
+
+    def boolean?
+      type.nil? || type == TrueClass || type == FalseClass
+    end
+
+    def default_value
+      boolean? ? (default.nil? ? false : default) : default
+    end
+
+    def long_flag
+      flag = "--#{name.to_s.tr('_', '-')}"
+      unless boolean?
+        flag += optional ? "=[VALUE]" : "=VALUE"
+      end
+      flag
+    end
+
+    def short_flag
+      "-#{short}" if short
+    end
+
+    def signature
+      [("#{short_flag}," if short), long_flag].compact.join(" ")
+    end
+
+    def attach(parser, store)
+      args = [short_flag, long_flag].compact
+      args << type if type && !boolean?
+      args << description if description
+
+      parser.on(*args) { |value| store[name] = value }
+    end
+  end
+end

data/lib/ergane/path_registry.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Ergane
+  # An ordered registry of path-prefix → label substitutions, used by
+  # Command#abbreviate_path. Ships with $HOME → "~"; consumers register
+  # their own, e.g.:
+  #
+  #   Ergane.paths.register("~/Workspace", "@ws")
+  #
+  # When abbreviating, the longest matching prefix wins, and a prefix only
+  # matches at a path boundary so "/home/user" never clips "/home/username".
+  class PathRegistry
+    Substitution = Struct.new(:prefix, :label)
+
+    def initialize
+      @substitutions = []
+    end
+
+    # Register a +prefix+ to collapse to +label+. The prefix is expanded
+    # (so "~" and relative paths resolve), and re-registering a prefix
+    # replaces its previous label. Returns self for chaining.
+    def register(prefix, label)
+      expanded = File.expand_path(prefix.to_s)
+      @substitutions.reject! { |sub| sub.prefix == expanded }
+      @substitutions << Substitution.new(expanded, label.to_s)
+      self
+    end
+
+    # Remove every registered substitution. Returns self for chaining.
+    def clear
+      @substitutions.clear
+      self
+    end
+
+    # 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)
+      original = path.to_s
+      expanded = File.expand_path(original)
+      best = @substitutions
+        .select { |sub| expanded == sub.prefix || expanded.start_with?("#{sub.prefix}/") }
+        .max_by { |sub| sub.prefix.length }
+      return original unless best
+
+      "#{best.label}#{expanded[best.prefix.length..]}"
+    end
+  end
+end

data/lib/ergane/runner.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module Ergane
+  class Runner
+    attr_reader :root, :argv
+
+    def initialize(root, argv)
+      @root = root
+      @argv = argv.dup
+    end
+
+    def execute
+      command_class, remaining, path = resolve(root, argv)
+
+      if help_requested?(remaining)
+        $stdout.puts HelpFormatter.new(command_class, command_path: path).format
+        return
+      end
+
+      if version_requested?(remaining) && command_class.respond_to?(:version) && command_class.version
+        $stdout.puts "#{command_class.command_name} #{command_class.version}"
+        return
+      end
+
+      instance = command_class.new(remaining)
+      instance.run(*instance.args)
+    end
+
+    private
+
+    def help_requested?(args)
+      args.include?("--help") || args.include?("-h")
+    end
+
+    def version_requested?(args)
+      args.include?("--version") || args.include?("-V")
+    end
+
+    def resolve(command_class, args, path = [])
+      path << (command_class.command_name || command_class.name || "command").to_s
+      return [command_class, args, path] if args.empty?
+
+      token = args.first
+      return [command_class, args, path] if token.start_with?("-")
+
+      sub = find_subcommand(command_class, token.to_sym)
+      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
+    end
+
+    def find_subcommand(command_class, token)
+      command_class.subcommands[token] ||
+        command_class.subcommands.each_value.find { |cmd| cmd.terms.include?(token) }
+    end
+  end
+end