lux-hammer 0.2.6 → 0.2.8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 173d405adff150c31284b295fbcc13b56d73a70d6752509f4954f5a89d5f4df7
-  data.tar.gz: 1439b6d6e44bec16a5571ffaec390d98ea945360862fb4514f55fedf89a575df
+  metadata.gz: 8e861fb5cdf9bbcc0533942927d96f35348fbb50614c1dd50b16279f1d81d2d3
+  data.tar.gz: 1a31f522be7d9c75847ce820169da0c5b9a4418522c224d3d284ce004ecbcd2d
 SHA512:
-  metadata.gz: 537c36703b561535f96fc6dd5454a2f6e01df6cac7059b8115b9c6ed176875edab529fbe0d530695d4bbc233fadb67964f2485baa8497de324e4a76b33de353b
-  data.tar.gz: 3abb187bb1fe58b03571fdbad1aac1e5a22a2023aeda4b8289ac0508813a85916bbc50a6b07b1988d9d888d3aff50b09658d77b5427704c1061a2c475c9bf151
+  metadata.gz: a1d7af3b3523903b10bf5a1b0af1d4d1c340b8a1a6736d6b9b0884f0cc0adca7eaa46079dfb24274147043c4e79b9a8ea497afcb7b6c80389ec73c4ee302d28f
+  data.tar.gz: e436739c8da3cb6dcfbd64135405930e70ba07eab53a5f1c880d3240319ce9c77118d61ba6fb766ef5817dfa54b0fa37fe17d1167236b4221afc156e04f3463f

data/.version

@@ -1 +1 @@
-0.2.6
+0.2.8

data/AGENTS.md

@@ -84,6 +84,12 @@ At class or `Hammerfile` scope:
 
 * `task :name do ... end`
 * `namespace :name do ... end`
+* `dotenv false` - opt out of auto `.env` / `.env.local` loading.
+  Only meaningful from the `hammer` binary (`Hammer.cli`); the load
+  happens after Hammerfile evaluation, before dispatch. Shell-set vars
+  always win (`ENV[k] ||= v`). For full dotenv-gem features
+  (interpolation, multiline) keep `dotenv false` and call `Dotenv.load`
+  from a `before` hook instead.
 * `load` / `load auto: true` / `load 'path/file.rb'` / `load 'glob/*.rb'` /
   `load 'some/dir'` - pull in Hammerfile fragments from `*_hammer.rb`
   files. Paths resolve relative to the caller's file. A directory
@@ -140,6 +146,23 @@ explicit ADR-level discussion. Keys:
 * The root `Hammer` subclass holds `@commands` and `@namespaces`.
 * `resolve('a:b:c')` walks `@namespaces['a'].namespaces['b']` and
   finds command `c` in the last class.
+* Each segment is fuzzy-matched: exact name/alt first, then prefix
+  (`b` -> `build`), then substring (`es` -> `test`). Per-scope: matching
+  only looks at this class's commands/namespaces, not globally across
+  the tree. Ambiguous fuzzy matches raise `Hammer::AmbiguousMatch`,
+  which `dispatch` catches and prints as
+  `multiple commands match 'b': bake, build`. Same fallback applies to
+  namespaces via `find_namespace`.
+* `resolve` and `resolve_namespace` return a `canonical` colon-path
+  alongside the resolved class/command, so help banners and the
+  pre-run banner display the canonical name even when the user typed
+  a fuzzy prefix.
+* Before a command's handler runs, `run_command` prints a gray
+  `> prog cmd --opt=val ARG` banner so it's visible which command was
+  actually picked when fuzzy matching kicks in. Only options that
+  differ from their default are listed; booleans render as `--flag`
+  / `--no-flag`. Help paths (`-h`, bare namespace) short-circuit
+  before the banner.
 * There is **no per-level dispatch**. A namespace is a container, not a
   CLI of its own. Do not reintroduce `subclass.start(remaining_argv)`.
 * `start(argv)` is a two-step pipeline: `split_chain(argv)` (private)

data/README.md

@@ -469,7 +469,7 @@ runs before every command in that scope (and its nested namespaces).
 Hooks fire outer -> inner, then the command's handler:
 
 ```ruby
-before { Dotenv.load }                  # runs before every command
+before { hammer :env }                  # runs before every command
 
 namespace :db do
   before { hammer :env }                # runs before every db:* command
@@ -479,6 +479,15 @@ namespace :db do
 end
 ```
 
+`.env` and `.env.local` next to the `Hammerfile` are loaded
+automatically by the `hammer` binary - no `before` hook needed.
+Shell-set vars are never overwritten, and `.env.local` overrides
+`.env`. Put `dotenv false` at the top of the Hammerfile to opt out:
+
+```ruby
+dotenv false                            # disable auto .env loading
+```
+
 `before` is intentionally not available inside `task` - the proc body
 *is* the command body, just put the setup line at the top of the proc.
 

data/lib/hammer/builder.rb

@@ -21,6 +21,11 @@ class Hammer
       @klass.before(&block)
     end
 
+    # Opt out of auto `.env` loading in `Hammer.cli`. Default is on.
+    def dotenv(flag = true)
+      @klass.dotenv(flag)
+    end
+
     # Same surface as `Hammer.load`. Resolved relative to the file that
     # called us, so `load auto: true` inside a Hammerfile picks up
     # *_hammer.rb under the Hammerfile's directory.
@@ -28,5 +33,33 @@ class Hammer
       anchor = Loader.caller_anchor(caller_locations(1, 1).first)
       @klass.loader.load(anchor, paths, kwargs)
     end
+
+    # instance_eval wrapper that also publishes the current Hammer target
+    # via Thread.current[:hammer_target]. That lets `*_hammer.rb` files
+    # pulled in through Ruby's own `require` (e.g. `Dir.require_all
+    # 'lib/tasks'` inside a Hammerfile) call `task`/`namespace`/`before`
+    # at top-level scope and have them register on the right target.
+    def evaluate(source = nil, path = nil, &block)
+      Hammer.with_target(@klass) do
+        block ? instance_eval(&block) : instance_eval(source, path)
+      end
+    end
+  end
+
+  # Top-level Hammer DSL. Extended onto `main` (below) so any file
+  # `require`d from within a Hammerfile - where `self == main` - can
+  # still call `task`, `namespace`, and `before`. Delegates to whichever
+  # Hammer subclass is currently being evaluated.
+  module DSL
+    %i[task namespace before dotenv].each do |m|
+      define_method(m) do |*args, &block|
+        target = Thread.current[:hammer_target]
+        raise Hammer::Error, "`#{m}` called outside a Hammer context " \
+                             '(Hammerfile / Hammer.run block / *_hammer.rb)' unless target
+        target.send(m, *args, &block)
+      end
+    end
   end
 end
+
+TOPLEVEL_BINDING.eval('self').extend(Hammer::DSL)

data/lib/hammer/dotenv.rb

@@ -0,0 +1,50 @@
+class Hammer
+  # Tiny built-in .env loader. Kept dependency-free on purpose - the
+  # gemspec advertises zero runtime deps.
+  #
+  # `Hammer.cli` calls `Dotenv.load(Dir.pwd)` after evaluating the
+  # Hammerfile (unless the Hammerfile said `dotenv false`), so vars
+  # from `.env` are available to every command handler.
+  #
+  # Semantics:
+  # * `.env` is loaded, then `.env.local` (latter overrides former).
+  # * Missing files are silently skipped - auto-load must not raise.
+  # * Existing `ENV[k]` always wins (`ENV[k] ||= v`); shell-set values
+  #   are never clobbered.
+  # * Supported lines: `KEY=value`, `KEY="value"`, `KEY='value'`, optional
+  #   leading `export `, `#` comments, blank lines.
+  # * NOT supported: `${VAR}` interpolation, multiline values, inline
+  #   comments after a value. Reach for the `dotenv` gem from a `before`
+  #   hook if you need those.
+  module Dotenv
+    FILES ||= %w[.env .env.local].freeze
+
+    def self.load(dir)
+      FILES.each do |name|
+        path = File.join(dir, name)
+        next unless File.file?(path)
+        parse(File.read(path)).each { |k, v| ENV[k] ||= v }
+      end
+    end
+
+    def self.parse(text)
+      out = {}
+      text.each_line do |line|
+        line = line.strip
+        next if line.empty? || line.start_with?('#')
+        line = line.sub(/\Aexport\s+/, '')
+        key, sep, val = line.partition('=')
+        next if sep.empty?
+        key = key.strip
+        next if key.empty?
+        val = val.strip
+        if (val.start_with?('"') && val.end_with?('"')) ||
+           (val.start_with?("'") && val.end_with?("'"))
+          val = val[1..-2]
+        end
+        out[key] = val
+      end
+      out
+    end
+  end
+end

data/lib/hammer/loader.rb

@@ -72,7 +72,7 @@ class Hammer
     def load_one(abs_path)
       return if @loaded[abs_path]
       @loaded[abs_path] = true
-      Builder.new(@target).instance_eval(File.read(abs_path), abs_path)
+      Builder.new(@target).evaluate(File.read(abs_path), abs_path)
     rescue Hammer::Error
       raise
     rescue StandardError => e

data/lib/hammer/option.rb

@@ -1,9 +1,9 @@
 class Hammer
   # Single option/flag definition.
   class Option
-    attr_reader :name, :type, :default, :desc, :aliases, :required
+    attr_reader :name, :type, :default, :desc, :aliases, :required, :placeholder
 
-    ALLOWED_KEYS    ||= %i[type default desc alias req].freeze
+    ALLOWED_KEYS    ||= %i[type default desc alias req placeholder].freeze
     RESERVED_FLAGS  ||= %w[-h --help].freeze
 
     def initialize(name, **opts)
@@ -13,12 +13,15 @@ class Hammer
               "unknown opt parameter(s) for :#{name}: #{bad.join(', ')}. " \
               "allowed: #{ALLOWED_KEYS.join(', ')}"
       end
-      @name     = name.to_sym
-      @type     = opts[:type] || :string
-      @default  = opts[:default]
-      @desc     = opts[:desc]
-      @aliases  = Array(opts[:alias]).map { |a| Option.normalize_alias(a) }
-      @required = opts[:req] ? true : false
+      @name        = name.to_sym
+      @type        = opts[:type] || :string
+      @default     = opts[:default]
+      @desc        = opts[:desc]
+      @aliases     = Array(opts[:alias]).map { |a| Option.normalize_alias(a) }
+      @required    = opts[:req] ? true : false
+      # Custom usage placeholder, e.g. `placeholder: 't/f'` -> `--log t/f`.
+      # Falls back to uppercased name (`--log LOG`) when nil.
+      @placeholder = opts[:placeholder]
 
       # Reserve -h / --help so every command supports them uniformly.
       if RESERVED_FLAGS.include?(switch)
@@ -60,7 +63,7 @@ class Hammer
 
     def usage
       flag = switch
-      flag += " #{name.to_s.upcase}" unless boolean?
+      flag += " #{placeholder || name.to_s.upcase}" unless boolean?
       line = aliases.empty? ? flag : "#{aliases.join(', ')}, #{flag}"
       suffix = annotation
       line = "#{line.ljust(28)} #{desc}" if desc

data/lib/lux-hammer.rb

@@ -5,6 +5,7 @@ require_relative 'hammer/command'
 require_relative 'hammer/loader'
 require_relative 'hammer/builder'
 require_relative 'hammer/command_builder'
+require_relative 'hammer/dotenv'
 
 # Thor-inspired tiny CLI builder.
 #
@@ -40,7 +41,11 @@ require_relative 'hammer/command_builder'
 class Hammer
   include Shell
 
-  Error ||= Class.new(StandardError)
+  Error          ||= Class.new(StandardError)
+  AmbiguousMatch ||= Class.new(Error)
+
+  # Gem version, read once from the bundled .version file.
+  VERSION ||= File.read(File.expand_path('../.version', __dir__)).strip
 
   class << self
     def inherited(sub)
@@ -178,7 +183,7 @@ class Hammer
       # "myapp ns:cmd" with the same prefix everywhere - and so the value
       # captured pre-chdir (see `Hammer.cli`) survives into nested classes.
       sub.instance_variable_set(:@program_name, program_name)
-      sub.class_eval(&block) if block
+      Hammer.with_target(sub) { sub.class_eval(&block) } if block
       @namespaces[name.to_s] = sub
     end
 
@@ -199,6 +204,18 @@ class Hammer
       @before_hooks
     end
 
+    # Toggle auto-loading of `.env` / `.env.local` for the `hammer`
+    # binary. Default is ON. Call `dotenv false` at the top of a
+    # Hammerfile to suppress. No-op for standalone `MyCli.start` -
+    # auto-load only fires from `Hammer.cli`.
+    def dotenv(flag = true)
+      @dotenv_enabled = flag
+    end
+
+    def dotenv_enabled?
+      @dotenv_enabled != false
+    end
+
     def parent
       @parent
     end
@@ -235,6 +252,18 @@ class Hammer
       @loader ||= Loader.new(self)
     end
 
+    # Push `klass` as the current Hammer target for the duration of the
+    # block. Top-level DSL methods (`task`, `namespace`, `before` - see
+    # `Hammer::DSL`) read this thread-local, so files `require`d from
+    # inside a Hammerfile register against the right target.
+    def with_target(klass)
+      prev = Thread.current[:hammer_target]
+      Thread.current[:hammer_target] = klass
+      yield
+    ensure
+      Thread.current[:hammer_target] = prev
+    end
+
     # Load Hammerfile fragments and register their commands on this
     # class. Rake-style: split a CLI across multiple files.
     #
@@ -295,60 +324,133 @@ class Hammer
       argv = argv.dup
       name = argv.shift
 
-      if name.nil? || name == 'help' || name == '-h' || name == '--help'
+      if name.nil?
+        # Bare invocation of the `hammer` binary: print a gem banner
+        # above the help so users can see which lux-hammer they have.
+        # Skipped for `-h` / `help` (those stay terse) and for user-
+        # built CLIs (their own program name, not lux-hammer).
+        if root.instance_variable_get(:@hammer_binary)
+          Shell.say "lux-hammer #{VERSION}"
+          Shell.say ''
+        end
+        return print_help
+      end
+
+      if name == 'help' || name == '-h' || name == '--help'
         target = argv.shift
         return print_help(target)
       end
 
-      # Trailing colon ("db:") -> expanded namespace listing with full
-      # per-command help on every task. Bare ":" expands the root.
+      # Trailing colon ("db:") -> namespace listing. Bare ":" lists root.
       if name.end_with?(':') && name != ':'
         bare = name.chomp(':')
-        ns = resolve_namespace(bare)
-        return print_namespace_help(bare, ns, full: true) if ns
+        ns, canonical = resolve_namespace(bare)
+        return print_namespace_help(canonical, ns) if ns
         Shell.print_error("unknown namespace: #{bare}")
         print_help
         exit 1
       elsif name == ':'
-        return print_help(nil, full: true)
+        return print_help
       end
 
-      cmd, owner = resolve(name)
-      return owner.run_command(cmd, argv, full: name) if cmd
+      cmd, owner, canonical = resolve(name)
+      return owner.run_command(cmd, argv, full: canonical) if cmd
 
-      ns = resolve_namespace(name)
-      return print_namespace_help(name, ns) if ns
+      ns, canonical = resolve_namespace(name)
+      return print_namespace_help(canonical, ns) if ns
 
       Shell.print_error("unknown command: #{name}")
       print_help
       exit 1
+    rescue AmbiguousMatch => e
+      Shell.print_error(e.message)
+      exit 1
     end
 
     public
 
-    # Find a command by canonical name or alt within this class.
+    # Find a command by canonical name or alt within this class. Falls
+    # back to fuzzy match (prefix first, then substring) when no exact
+    # hit. Raises AmbiguousMatch if the fuzzy pass matches more than one.
     def find_command(name)
-      commands[name.to_s] || commands.values.find { |c| c.matches?(name) }
+      name = name.to_s
+      exact = commands[name] || commands.values.find { |c| c.matches?(name) }
+      return exact if exact
+      fuzzy_pick(name, commands.values, 'command') { |c| [c.name, *c.alts] }
+    end
+
+    # Find a namespace by name within this class. Same fuzzy fallback
+    # as find_command.
+    def find_namespace(name)
+      name = name.to_s
+      return namespaces[name] if namespaces.key?(name)
+      pair = fuzzy_pick(name, namespaces.to_a, 'namespace') { |p| [p.first] }
+      pair&.last
+    end
+
+    # Returns the command at the parent that shares its name with this
+    # namespace. E.g. for path "gem:version" returns the `version` command
+    # in the `gem` namespace (if defined), so `gem:version:` listings can
+    # include `gem:version` itself at the top.
+    def find_namespace_sibling(canonical)
+      parts = canonical.to_s.split(':')
+      return nil if parts.empty?
+      parent = self
+      parts[0..-2].each do |seg|
+        parent = parent.namespaces[seg] or return nil
+      end
+      parent.commands[parts.last]
     end
 
-    # Walk "ns1:ns2:cmd" -> [command, owning_class]. Returns [nil, nil]
-    # if any segment is missing or the final segment isn't a command.
+    # Walk "ns1:ns2:cmd" -> [command, owning_class, canonical_path].
+    # Returns [nil, nil, nil] if any segment is missing or the final
+    # segment isn't a command. canonical_path uses the canonical name
+    # of every segment (so a fuzzy `b` resolves to `build` in the path).
     def resolve(path)
       parts = path.to_s.split(':')
       klass = self
+      canonical = []
       parts[0..-2].each do |ns|
-        klass = klass.namespaces[ns] or return [nil, nil]
+        sub = klass.find_namespace(ns) or return [nil, nil, nil]
+        canonical << klass.namespaces.key(sub)
+        klass = sub
       end
       cmd = klass.find_command(parts.last)
-      cmd ? [cmd, klass] : [nil, nil]
+      return [nil, nil, nil] unless cmd
+      canonical << cmd.name
+      [cmd, klass, canonical.join(':')]
     end
 
-    # Walk "ns1:ns2" -> namespace class, or nil if any segment missing.
+    # Walk "ns1:ns2" -> [namespace_class, canonical_path].
+    # Returns [nil, nil] if any segment is missing.
     def resolve_namespace(path)
       parts = path.to_s.split(':')
       klass = self
-      parts.each { |ns| klass = klass.namespaces[ns] or return nil }
-      klass
+      canonical = []
+      parts.each do |ns|
+        sub = klass.find_namespace(ns) or return [nil, nil]
+        canonical << klass.namespaces.key(sub)
+        klass = sub
+      end
+      [klass, canonical.join(':')]
+    end
+
+    # Shared fuzzy matcher used by find_command and find_namespace.
+    # The block returns the strings to match against for each item
+    # (canonical name plus alts for commands, just the key for namespaces).
+    # Tries prefix match first, then substring; raises AmbiguousMatch
+    # when either pass hits more than one item.
+    def fuzzy_pick(name, items, kind, &keys_for)
+      [:start_with?, :include?].each do |op|
+        matches = items.select { |item| keys_for.call(item).any? { |k| k.send(op, name) } }
+        next if matches.empty?
+        if matches.size > 1
+          labels = matches.map { |m| keys_for.call(m).first }.sort
+          raise AmbiguousMatch, "multiple #{kind}s match '#{name}': #{labels.join(', ')}"
+        end
+        return matches.first
+      end
+      nil
     end
 
     # Programmatic dispatch by name. Useful for scripting and tests.
@@ -394,6 +496,7 @@ class Hammer
 
       positional, opts = Parser.new(cmd.options).parse(argv)
       opts[:args] = positional
+      print_run_banner(cmd, full || cmd.name, positional, opts)
       instance = new
       run_before_hooks(instance, opts)
       run_needs(cmd)
@@ -409,6 +512,25 @@ class Hammer
       exit 1
     end
 
+    # Print a gray "> prog cmd --opt=val ARG" banner before a command
+    # runs. Helps see what was actually picked when fuzzy matching
+    # resolved a partial name. Only opts that differ from their default
+    # are shown; booleans render as `--flag` / `--no-flag`.
+    def print_run_banner(cmd, full, positional, opts)
+      parts = ["#{program_name} #{full}"]
+      cmd.options.each do |o|
+        val = opts[o.name]
+        next if val.nil? || val == o.default
+        if o.boolean?
+          parts << (val ? "--#{o.name}" : "--no-#{o.name}")
+        else
+          parts << "--#{o.name}=#{val}"
+        end
+      end
+      parts.concat(positional)
+      Shell.say "> #{parts.join(' ')}", :gray
+    end
+
     # Fire `before` hooks from root down through the namespace chain.
     # Each class's hooks fire at most once per top-level `start`, so
     # prereqs dispatched via `needs` won't re-trigger them.
@@ -444,18 +566,18 @@ class Hammer
 
     def print_help(target = nil, full: false)
       if target
-        # `help ns:` is equivalent to `ns:` - expanded namespace listing.
+        # `help ns:` is equivalent to `ns:` - namespace listing.
         if target.end_with?(':') && target != ':'
           bare = target.chomp(':')
-          ns = resolve_namespace(bare)
-          return print_namespace_help(bare, ns, full: true) if ns
+          ns, canonical = resolve_namespace(bare)
+          return print_namespace_help(canonical, ns) if ns
           Shell.print_error("unknown: #{target}")
           return
         end
-        cmd, _ = resolve(target)
-        return print_command_help(cmd, target) if cmd
-        ns = resolve_namespace(target)
-        return print_namespace_help(target, ns, full: full) if ns
+        cmd, _, canonical = resolve(target)
+        return print_command_help(cmd, canonical) if cmd
+        ns, canonical = resolve_namespace(target)
+        return print_namespace_help(canonical, ns, full: full) if ns
         Shell.print_error("unknown: #{target}")
         return
       end
@@ -473,11 +595,15 @@ class Hammer
 
     def print_namespace_help(prefix, ns, full: false)
       Shell.say "Usage: #{program_name} #{prefix}:COMMAND [ARGS]", :cyan
-      if full
-        ns.each_command(prefix) { |path, c| print_full_block(path, c) unless c.desc.empty? }
-      else
+      rows = []
+      sibling = find_namespace_sibling(prefix)
+      rows << [prefix, sibling] if sibling && !sibling.desc.empty?
+      ns.each_command(prefix) { |path, c| rows << [path, c] unless c.desc.empty? }
+      unless rows.empty?
         Shell.say ''
-        print_command_list(ns, prefix)
+        Shell.say 'Commands:', :yellow
+        width = rows.map { |path, _| path.length }.max
+        emit_rows(rows.sort_by { |path, _| [path.count(':'), path] }, width)
       end
       print_global_flags
       print_footer
@@ -620,11 +746,11 @@ class Hammer
   def self.run(argv = ARGV, &block)
     klass = Class.new(Hammer)
     if block
-      Builder.new(klass).instance_eval(&block)
+      Builder.new(klass).evaluate(&block)
     else
       hf = File.join(Dir.pwd, 'Hammerfile')
       if File.file?(hf)
-        Builder.new(klass).instance_eval(File.read(hf), hf)
+        Builder.new(klass).evaluate(File.read(hf), hf)
       else
         klass.loader.load(Dir.pwd, [], auto: true)
       end
@@ -699,7 +825,11 @@ class Hammer
     # chdir into the Hammerfile's directory for the entire run so commands
     # operate on the project root (Rake-style).
     Dir.chdir(File.dirname(path))
-    Builder.new(klass).instance_eval(File.read(path), path)
+    Builder.new(klass).evaluate(File.read(path), path)
+    # Auto-load `.env` / `.env.local` after eval so a top-level
+    # `dotenv false` in the Hammerfile can suppress it. Trade-off: vars
+    # are NOT visible during Hammerfile evaluation, only inside handlers.
+    Hammer::Dotenv.load(Dir.pwd) if klass.dotenv_enabled?
     klass.start(argv)
   end
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: lux-hammer
 version: !ruby/object:Gem::Version
-  version: 0.2.6
+  version: 0.2.8
 platform: ruby
 authors:
 - Dino Reic
@@ -38,6 +38,7 @@ files:
 - "./lib/hammer/builder.rb"
 - "./lib/hammer/command.rb"
 - "./lib/hammer/command_builder.rb"
+- "./lib/hammer/dotenv.rb"
 - "./lib/hammer/loader.rb"
 - "./lib/hammer/option.rb"
 - "./lib/hammer/parser.rb"
@@ -62,7 +63,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.10
+rubygems_version: 4.0.11
 specification_version: 4
 summary: Thor-inspired tiny CLI builder
 test_files: []