lux-hammer 0.1.1 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: dc61ff9ad69572e54aff2624ada68e0acdfc98da3cf3751d36034b93c2bb0bcd
-  data.tar.gz: 8fe3cc67068249499ac5600cf2842c5532d7664c28490f2469c4c2ef3306672b
+  metadata.gz: 17ad95331316a0cd95554605d58b2a7dce64f9db9d6adc997b34cf5f3b1e2b1a
+  data.tar.gz: 633ad47b777e68b848f11552e5345d5b468e01a0fa27a273dc6551aac7d18af1
 SHA512:
-  metadata.gz: 7cf2c00b2b87205b80a3f662dcbdfc0a46531ba5aabe4d1402910740111e75476f9c9b88431db5b18c1d9e62c05e6a7a540faada36e82453dacd975c4f00f03c
-  data.tar.gz: 517f66e40cda59a344a14653d3c9b14e16dc87d51750d28c7c83e4be67db9f344e047ea928e2d13bfe1b8f7e83ab7283ef5c26982567be4488cf45e9d89ea792
+  metadata.gz: '0568fccc6f143b0671166a08c1853a3f682bf2c4c5488791fa7d46e1c4d8b3cc311ae29a016e9cf9a93f2cc31a577a551af72f0f4754cc9e9bd3adb66c5f6731'
+  data.tar.gz: bf5e04d1e37e50f138c7c14079b889018f85bda195dad8676df4f634a37fe62414a1511a451aacb08f1e0860651426d8a7bca78cf3bad35b1fbf3dc137423438

data/.version

@@ -1 +1 @@
-0.1.1
+0.2.1

data/README.md

@@ -27,7 +27,7 @@ Create a `Hammerfile` in your project root:
 define :hello do
   desc 'say hi'
   proc do |opts|
-    say "hello #{opts[:args].first || 'world'}", :green
+    say.green "hello #{opts[:args].first || 'world'}"
   end
 end
 ```
@@ -143,7 +143,7 @@ define :build do
   opt :env,     default: 'dev'
 
   proc do |opts|
-    say "building #{opts[:env]}", :green
+    say.green "building #{opts[:env]}"
   end
 end
 ```
@@ -154,13 +154,11 @@ For when you'd rather write a Ruby method:
 
 ```ruby
 class MyCli < Hammer
-  program_name 'mycli'
-
   desc 'Build the project'
   opt :verbose, type: :boolean, alias: :v
   opt :env,     default: 'dev'
   def build(opts)
-    say "building #{opts[:env]}", :green
+    say.green "building #{opts[:env]}"
   end
 
   desc 'Ping with no opts'
@@ -178,22 +176,6 @@ without opts; methods that take an argument receive the opts hash.
 
 Both styles can coexist in the same class.
 
-## Program name
-
-`program_name 'foo'` (alias `program 'foo'`) sets the name shown in
-help/usage output. It is **optional**. When omitted, the default is:
-
-* the invocation path **relative to cwd** if the script lives inside
-  the current working directory (e.g. `bin/foo` when invoked from the
-  project root as `./bin/foo` or `bin/foo`), or
-* the **basename** of `$PROGRAM_NAME` otherwise (e.g. `lux` for a
-  globally installed bin in `PATH`).
-
-So a project-local wrapper at `bin/foo` shows up in help as
-`Usage: bin/foo COMMAND [ARGS]`, while the same library invoked
-through a globally installed `lux` shim shows `Usage: lux ...`. Set
-`program 'whatever'` explicitly to override.
-
 ## Options (`opt`)
 
 ### Declaration
@@ -434,6 +416,84 @@ hammer db:migrate -h      # per-command help
 Namespaces nest to any depth. There is no per-level dispatch - the root
 parses the whole colon path and walks the namespace tree.
 
+## Pre-hooks (`before`)
+
+A `before do ... end` block at the root scope or inside a `namespace`
+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
+
+namespace :db do
+  before { hammer_env }                 # runs before every db:* command
+  define :migrate do
+    proc { |opts| ... }                 # no boilerplate require inside
+  end
+end
+```
+
+`before` is intentionally not available inside `define` - the proc body
+*is* the command body, just put the setup line at the top of the proc.
+
+Pairs naturally with hidden commands (next section): keep `:env` /
+`:app` setup as undocumented helpers and pull them in via `before`.
+
+## Hidden commands (no `desc`)
+
+A command declared without a `desc` is **hidden from help listings**
+but stays fully dispatchable and `hammer_*`-callable:
+
+```ruby
+define :env do
+  proc { |_| require './config/env' }   # no desc -> hidden
+end
+
+namespace :db do
+  before { hammer_env }                 # call it from a hook
+  define :migrate do
+    desc 'Run migrations'
+    proc { |_| ... }
+  end
+end
+```
+
+`hammer` and `hammer db` won't list `env`, but `hammer env`,
+`hammer_env` from another proc, and `before { hammer_env }` all work.
+
+## Prereqs (`needs`)
+
+Declare commands that must run before this one (Rake-style task deps):
+
+```ruby
+define :env do
+  proc { |_| require './config/env' }     # hidden helper
+end
+
+define :app do
+  needs :env                              # runs `env` first
+  desc 'start the app'
+  proc { |opts| App.start }
+end
+
+define :deploy do
+  needs :env, :build                      # multiple prereqs, in order
+  proc { |opts| ... }
+end
+```
+
+Prereq names are colon paths resolved against the root class - same
+lookup as `hammer_*`. Use `needs 'db:env'` to depend on a namespaced
+command.
+
+Each prereq fires **at most once per top-level invocation**, so if
+`:app` needs `:env` and `:build` also needs `:env`, `:env` still runs
+only once. Prereqs run with default options (no argv passed through).
+
+`needs` vs `before`:
+* `before { hammer_env }` - fires for *every* command in a scope.
+* `needs :env` - declared per command, deduped across the call chain.
+
 ## Command aliases (`alt`)
 
 `alt :short_name` (or several) registers extra names for a command:
@@ -459,7 +519,7 @@ define :deploy do
   proc do |opts|
     hammer_build(env: 'prod', verbose: true)
     hammer_db_migrate
-    say 'deployed', :green
+    say.green 'deployed'
   end
 end
 ```
@@ -481,19 +541,111 @@ class level, useful for tests and scripting.
 
 ## Shell helpers
 
-Available inside any handler:
+These are mixed into every handler (and also live on `Hammer::Shell` for
+direct use).
+
+### `say` - print a line
+
+```ruby
+say 'plain output'             # no color
+say.green 'ok'                 # color via proxy (preferred)
+say.cyan  "env=#{env}"         # interpolation works the same
+say 'equivalent', :green       # two-arg form is still supported
+say ''                         # blank line
+```
+
+`say` with no args returns a tiny proxy that exposes one method per
+color: `say.red 'x'` is just `say('x', :red)`. The proxy form reads
+better when colors are the common case. Use `say ''` for an explicit
+blank line.
+
+### `String#color` - paint a string without printing
+
+```ruby
+label = 'OK'.color(:green)
+puts "[#{label}] done"         # embed colored chunks anywhere
+
+Hammer::Shell.paint('x', :red) # the underlying primitive `say` uses
+```
+
+### Colors
+
+Valid names: `:black :red :green :yellow :blue :magenta :cyan :white :gray`.
+Unknown colors (in `say`, `say.<color>`, `paint`, or `String#color`)
+raise `Hammer::Error` listing the valid names - even when colors are
+disabled, so typos fail loudly in CI.
+
+Colors are auto-disabled when stdout isn't a TTY or when `NO_COLOR` is
+set. Force on/off programmatically:
+
+```ruby
+Hammer::Shell.color!(true)     # force ANSI on
+Hammer::Shell.color!(false)    # force off
+Hammer::Shell.color?           # current state (bool)
+```
+
+### `error` - controlled failure
+
+```ruby
+error 'config file missing' unless File.exist?('config.yml')
+# -> dispatcher prints "[error] config file missing" in red, exits 1
+# No backtrace, no per-command help spam.
+```
+
+Internally it just raises `Hammer::Error`; the dispatcher catches it.
+
+### `ask` - read one line from stdin
+
+```ruby
+name = ask 'your name'                       # required-style prompt
+env  = ask 'env', default: 'dev'             # blank input -> "dev"
+```
+
+The prompt is shown in cyan with the default in brackets when present.
+Returns the typed line (chomped) or the default on a blank line.
+
+### `yes?` - y/N confirmation
 
 ```ruby
-say 'ok', :green
-say 'big', :yellow, bold: true
-error 'something broke'        # prints + exits 1 (raises Hammer::Error)
-name = ask 'name', default: 'world'
-exit 0 unless yes? 'continue?'
-sh 'bundle install'            # echoes "$ bundle install", aborts on non-zero
+exit 0 unless yes? 'continue?'               # anything starting with y/Y -> true
+                                             # blank, n, anything else -> false
 ```
 
-Colors are auto-disabled when stdout isn't a TTY, when `NO_COLOR` is
-set, or programmatically via `Hammer::Shell.color!(false)`.
+### `choose` - arrow-key picker
+
+```ruby
+envs = %w[dev staging prod]
+idx  = choose 'Pick env', envs
+say.green "deploying to #{envs[idx]}" if idx
+```
+
+While the picker is up: `j`/`k` or `↑`/`↓` to move, `Enter` to confirm,
+`q` / `ESC` / Ctrl-C to cancel. Returns the integer index of the
+selected item, or `nil` on cancel.
+
+When stdin isn't a TTY (pipes, redirected scripts, tests), `choose`
+falls back to a numbered prompt: it prints each item with a number and
+reads a line - same return contract, so calling code doesn't change.
+
+```
+$ echo 2 | mycli some-cmd
+Pick env
+  1) dev
+  2) staging
+  3) prod
+select [1-3]:
+# idx -> 1 (zero-based)
+```
+
+### `sh` - run a shell command, abort on failure
+
+```ruby
+sh 'bundle install'                          # echoes "$ bundle install" in gray
+sh "git tag v#{version}"                     # raises Hammer::Error on non-zero
+```
+
+Returns `true` on success. On non-zero exit it raises `Hammer::Error`,
+which the dispatcher turns into `[error] command failed: ...` + exit 1.
 
 ## Splitting across files (`load`)
 
@@ -502,7 +654,6 @@ in any file ending in `_hammer.rb` and pull them in with `load`:
 
 ```ruby
 # Hammerfile
-program 'demo'
 load auto: true              # recursive scan for *_hammer.rb from here
 ```
 
@@ -512,7 +663,7 @@ namespace :db do
   define :migrate do
     desc 'Run pending migrations'
     opt :pretend, type: :boolean, alias: :p
-    proc { |o| say "migrating pretend=#{o[:pretend].inspect}", :green }
+    proc { |o| say.green "migrating pretend=#{o[:pretend].inspect}" }
   end
 end
 ```
@@ -523,7 +674,7 @@ define :deploy do
   desc 'Deploy to prod'
   proc do |_|
     hammer_db_migrate        # cross-file invocation just works
-    say 'deployed', :cyan
+    say.cyan 'deployed'
   end
 end
 ```
@@ -536,12 +687,18 @@ load auto: true              # recursive scan for *_hammer.rb under caller dir
 load 'tasks/db_hammer.rb'    # one file (path relative to caller)
 load 'tasks/*_hammer.rb'     # glob
 load 'a.rb', 'b.rb'          # several explicit paths
+load 'tasks'                 # directory -> recursive scan under it (empty OK)
 ```
 
 Paths resolve relative to the file calling `load`, not cwd. Inside a
 `Hammerfile` that means "relative to the Hammerfile"; inside a class
 body it means "relative to that file".
 
+A directory argument is the explicit-anchor twin of `load auto: true` -
+walks the directory for `*_hammer.rb` with the same skip rules. Useful
+when you want to pull fragments from a known sibling tree without
+making it the caller's dir.
+
 ### What's skipped
 
 Auto-discovery walks recursively but skips `.git`, `.bundle`,
@@ -575,26 +732,49 @@ Same shape as a Hammerfile, just inline:
 require 'lux-hammer'
 
 Hammer.run(ARGV) do
-  program 'inline'
-
   define :hello do
     desc 'say hi'
     opt :loud, type: :boolean, alias: :l
     proc do |opts|
       msg = "hello #{opts[:args].first || 'world'}"
       msg = msg.upcase if opts[:loud]
-      say msg, :cyan
+      say.cyan msg
     end
   end
 end
 ```
 
-## Complete example (every feature)
+### `Hammer.run` without a block
+
+If you call `Hammer.run(ARGV)` with no block, it does the obvious thing
+relative to `Dir.pwd`:
+
+* If `./Hammerfile` exists, it's evaluated as the block DSL.
+* Otherwise, `*_hammer.rb` files under `Dir.pwd` are auto-discovered
+  (same walk + skip rules as `load auto: true`).
+
+Either way ARGV is dispatched against the resulting CLI. Useful for a
+one-line custom bin:
 
 ```ruby
-# Hammerfile
-program 'demo'
+#!/usr/bin/env ruby
+require 'lux-hammer'
+Hammer.run ARGV
+```
+
+For more control - e.g. loading a Hammerfile from a fixed path *and*
+auto-discovering from cwd - pass a block and use `load` explicitly:
+
+```ruby
+Hammer.run ARGV do
+  load File.join(MY_ROOT, 'Hammerfile')
+  load Dir.pwd if Dir.pwd != MY_ROOT
+end
+```
+
+## Complete example (every feature)
 
+```ruby
 # Simple top-level command
 define :build do
   desc    'Build the project'
@@ -605,7 +785,7 @@ define :build do
 
   proc do |opts|
     target = opts[:args].first || opts[:env]
-    say "building #{target}", :green, bold: true
+    say.green "building #{target}"
     say '  verbose on' if opts[:verbose]
   end
 end
@@ -620,7 +800,7 @@ define :deploy do
   proc do |opts|
     hammer_build(env: 'prod')
     exit 0 unless yes? "deploy to #{opts[:url]}?" unless opts[:force]
-    say "deploying to #{opts[:url]}", :yellow
+    say.yellow "deploying to #{opts[:url]}"
   end
 end
 
@@ -634,7 +814,7 @@ namespace :db do
 
     proc do |opts|
       step = opts[:args].first || 'all'
-      say "migrating #{step} pretend=#{opts[:pretend].inspect}", :green
+      say.green "migrating #{step} pretend=#{opts[:pretend].inspect}"
     end
   end
 
@@ -645,7 +825,7 @@ namespace :db do
       opt :limit, type: :integer, default: 100
 
       proc do |opts|
-        say "users role=#{opts[:role]} limit=#{opts[:limit]}", :cyan
+        say.cyan "users role=#{opts[:role]} limit=#{opts[:limit]}"
       end
     end
 
@@ -719,8 +899,6 @@ directly. Useful for embedding or testing:
 require 'lux-hammer'
 
 class MyCli < Hammer
-  program_name 'mycli'
-
   define :greet do
     opt :loud, type: :boolean
     proc do |opts|

data/lib/hammer/builder.rb

@@ -19,6 +19,12 @@ class Hammer
       @klass.namespace(name, &block)
     end
 
+    # Per-target / per-namespace pre-hook. Same semantics as
+    # `Hammer.before` at the class level - see lux-hammer.rb.
+    def before(&block)
+      @klass.before(&block)
+    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.

data/lib/hammer/command.rb

@@ -1,7 +1,7 @@
 class Hammer
   # A single registered command on a Hammer class.
   class Command
-    attr_reader :name, :desc, :options, :examples, :alts
+    attr_reader :name, :desc, :options, :examples, :alts, :needs
     attr_accessor :handler
 
     def initialize(name:, desc: '', handler: nil)
@@ -11,6 +11,7 @@ class Hammer
       @options  = []
       @examples = []
       @alts     = []
+      @needs    = []
     end
 
     # First line of `desc`, used in the flat command listing.
@@ -30,6 +31,10 @@ class Hammer
       @alts << name.to_s
     end
 
+    def add_need(name)
+      @needs << name.to_s
+    end
+
     def matches?(name)
       name = name.to_s
       name == @name || @alts.include?(name)

data/lib/hammer/command_builder.rb

@@ -22,5 +22,9 @@ class Hammer
     def alt(*names)
       names.each { |n| @cmd.add_alt(n) }
     end
+
+    def needs(*names)
+      names.each { |n| @cmd.add_need(n) }
+    end
   end
 end

data/lib/hammer/loader.rb

@@ -38,16 +38,16 @@ class Hammer
 
     def resolve_pattern(anchor, pattern)
       abs = File.expand_path(pattern, anchor)
-      matches =
-        if abs.match?(/[\*\?\[\{]/)
-          Dir.glob(abs)
-        elsif File.file?(abs)
-          [abs]
-        else
-          []
-        end
-      raise Hammer::Error, "load: no files matched #{pattern.inspect}" if matches.empty?
-      matches.sort
+      if abs.match?(/[\*\?\[\{]/)
+        matches = Dir.glob(abs).sort
+        raise Hammer::Error, "load: no files matched #{pattern.inspect}" if matches.empty?
+        return matches
+      end
+      # Directory: discover *_hammer.rb under it. Empty result is OK
+      # (an app may legitimately have no fragments).
+      return discover(abs) if File.directory?(abs)
+      return [abs] if File.file?(abs)
+      raise Hammer::Error, "load: no files matched #{pattern.inspect}"
     end
 
     def discover(dir)

data/lib/hammer/shell.rb

@@ -1,3 +1,5 @@
+require 'io/console'
+
 class Hammer
   # ANSI color/output helpers. Mixed into command instances; also callable
   # directly as `Hammer::Shell.say(...)`.
@@ -19,15 +21,33 @@ class Hammer
       @color = value
     end
 
-    def paint(text, color = nil, bold: false)
-      return text.to_s unless color? && (color || bold)
-      code = COLORS[color] || 0
-      prefix = bold ? "\e[1;#{code}m" : "\e[#{code}m"
-      "#{prefix}#{text}\e[0m"
+    def paint(text, color = nil)
+      if color && !COLORS.key?(color)
+        raise Hammer::Error, "unknown color #{color.inspect} (valid: #{COLORS.keys.join(', ')})"
+      end
+      return text.to_s unless color? && color
+      "\e[#{COLORS[color]}m#{text}\e[0m"
+    end
+
+    # `say` with no args returns a proxy so you can write `say.cyan 'hi'`.
+    # `say('')` still prints a blank line; `say('x', :cyan)` is unchanged.
+    def say(text = nil, color = nil)
+      return SayProxy.new if text.nil?
+      puts paint(text, color)
     end
 
-    def say(text = '', color = nil, bold: false)
-      puts paint(text, color, bold: bold)
+    class SayProxy
+      COLORS.each_key do |name|
+        define_method(name) { |text = ''| Shell.say(text, name) }
+      end
+
+      def method_missing(name, *)
+        raise Hammer::Error, "unknown color :#{name} (valid: #{COLORS.keys.join(', ')})"
+      end
+
+      def respond_to_missing?(_name, _include_private = false)
+        false
+      end
     end
 
     # Raise a controlled Hammer::Error. If unhandled, the dispatcher
@@ -41,7 +61,7 @@ class Hammer
     # Print a red [error] line to stderr (does not exit). Used internally
     # by the dispatcher to render Hammer::Error messages.
     def print_error(text)
-      warn paint("[error] #{text}", :red, bold: true)
+      warn paint("[error] #{text}", :red)
     end
 
     def ask(prompt, default: nil)
@@ -59,6 +79,75 @@ class Hammer
       answer.to_s.strip.downcase.start_with?('y')
     end
 
+    # Arrow-key picker. Returns the chosen index, or nil on cancel
+    # (ESC, Ctrl-C, q). Non-TTY input falls back to a numbered prompt
+    # so this stays scriptable.
+    #
+    #   idx = choose 'Pick env', %w[dev staging prod]
+    #   say.green "chose #{ %w[dev staging prod][idx] }" if idx
+    def choose(prompt, items)
+      items = items.to_a
+      error 'choose needs at least one item' if items.empty?
+
+      say.cyan prompt
+
+      return choose_numbered(items) unless $stdin.tty? && $stdin.respond_to?(:raw)
+
+      selected = 0
+      redraw = lambda do |highlight = :cyan|
+        items.each_with_index do |item, i|
+          puts(i == selected ? paint("> #{item}", highlight) : "  #{item}")
+        end
+      end
+      redraw.call
+
+      $stdout.print "\e[?25l" # hide cursor
+      begin
+        $stdin.raw do |io|
+          loop do
+            ch = io.getch
+            case ch
+            when "\r", "\n"
+              # Collapse the list to the chosen line, in green.
+              $stdout.print "\e[#{items.size}A\e[J"
+              puts paint("> #{items[selected]}", :green)
+              return selected
+            when "\x03", 'q' # Ctrl-C, q
+              $stdout.print "\e[#{items.size}A\e[J"
+              return nil
+            when "\e"
+              # ESC may stand alone or start an arrow sequence \e[A / \e[B.
+              if IO.select([io], nil, nil, 0.01) && io.getch == '['
+                case io.getch
+                when 'A' then selected = (selected - 1) % items.size
+                when 'B' then selected = (selected + 1) % items.size
+                end
+              else
+                $stdout.print "\e[#{items.size}A\e[J"
+                return nil
+              end
+            when 'k' then selected = (selected - 1) % items.size
+            when 'j' then selected = (selected + 1) % items.size
+            end
+            $stdout.print "\e[#{items.size}A\e[J"
+            redraw.call
+          end
+        end
+      ensure
+        $stdout.print "\e[?25h" # show cursor
+      end
+    end
+
+    # Fallback for non-TTY stdin (pipes, tests). Returns the index or nil.
+    def choose_numbered(items)
+      items.each_with_index { |item, i| puts "  #{i + 1}) #{item}" }
+      print paint("select [1-#{items.size}]: ", :cyan)
+      line = $stdin.gets
+      return nil if line.nil?
+      idx = line.strip.to_i - 1
+      idx.between?(0, items.size - 1) ? idx : nil
+    end
+
     # Run a shell command. Echoes the command in gray, raises
     # Hammer::Error on non-zero exit. Returns true on success.
     def sh(cmd)
@@ -68,3 +157,10 @@ class Hammer
     end
   end
 end
+
+# `"hi".color(:cyan)` -> ANSI-painted string. Raises on unknown color.
+class String
+  def color(name)
+    Hammer::Shell.paint(self, name)
+  end
+end

data/lib/lux-hammer.rb

@@ -50,11 +50,14 @@ class Hammer
       super
       sub.instance_variable_set(:@commands, {})
       sub.instance_variable_set(:@namespaces, {})
+      sub.instance_variable_set(:@before_hooks, [])
+      sub.instance_variable_set(:@parent, nil)
       sub.instance_variable_set(:@program_name, nil)
       sub.instance_variable_set(:@pending_desc, nil)
       sub.instance_variable_set(:@pending_examples, [])
       sub.instance_variable_set(:@pending_options, [])
       sub.instance_variable_set(:@pending_alts, [])
+      sub.instance_variable_set(:@pending_needs, [])
     end
 
     # ----- class-level DSL for `def`-style commands ---------------------
@@ -72,6 +75,7 @@ class Hammer
     def example(text)    ; @pending_examples << text end
     def opt(name, **o)   ; @pending_options << Option.new(name, **o) end
     def alt(*names)      ; @pending_alts.concat(names) end
+    def needs(*names)    ; @pending_needs.concat(names) end
 
     def method_added(method_name)
       super
@@ -81,6 +85,7 @@ class Hammer
       @pending_examples.each { |e| cmd.add_example(e) }
       @pending_options.each  { |o| cmd.add_option(o) }
       @pending_alts.each     { |n| cmd.add_alt(n) }
+      @pending_needs.each    { |n| cmd.add_need(n) }
 
       # If the method takes no args, call it without opts. Otherwise pass
       # opts. So both `def build` and `def build(opts)` work.
@@ -93,6 +98,7 @@ class Hammer
       @pending_examples = []
       @pending_options  = []
       @pending_alts     = []
+      @pending_needs    = []
     end
 
     def program_name(name = nil)
@@ -149,6 +155,7 @@ class Hammer
       @pending_examples = []
       @pending_options  = []
       @pending_alts     = []
+      @pending_needs    = []
     end
 
     # Open a namespace (group of commands). Everything inside the block
@@ -165,6 +172,9 @@ class Hammer
       # (`hammer_<colon_path>`) from inside a namespaced command dispatches
       # against the full tree, not just the current namespace.
       sub.instance_variable_set(:@root, root)
+      # Parent link, so `before` hooks defined further up the namespace
+      # tree can be collected and run outer -> inner before a command.
+      sub.instance_variable_set(:@parent, self)
       # Inherit program_name so help banners show "myapp ns:cmd", not
       # whichever binary the namespace class fell back to.
       sub.program_name(program_name) if @program_name
@@ -172,6 +182,38 @@ class Hammer
       @namespaces[name.to_s] = sub
     end
 
+    # Register a hook to run before every command in this class (root or
+    # namespace). Hooks receive the command's `opts` hash. All hooks run
+    # outer -> inner, once per top-level `start` (prereqs don't re-trigger).
+    #
+    #   before { |opts| Dotenv.load }
+    #   namespace :db do
+    #     before { hammer_env }
+    #     define :migrate do ... end
+    #   end
+    def before(&block)
+      before_hooks << block
+    end
+
+    def before_hooks
+      @before_hooks
+    end
+
+    def parent
+      @parent
+    end
+
+    # Root -> ... -> self. Used to gather `before` hooks for a command.
+    def ancestor_chain
+      chain = []
+      klass = self
+      while klass
+        chain.unshift klass
+        klass = klass.parent
+      end
+      chain
+    end
+
     # Topmost class in this CLI tree. For user-defined `class MyCli < Hammer`
     # or `Class.new(Hammer)` it's self; for namespace subclasses it's
     # whichever class opened the namespace.
@@ -216,6 +258,14 @@ class Hammer
     # Command names are Rake-style colon paths: "build", "db:migrate",
     # "db:users:list".
     def start(argv = ARGV)
+      # Track prereqs fired during this top-level invocation so a `needs`
+      # chain runs each prereq at most once. Nested `start` calls (e.g.
+      # `needs` -> `hammer_*` -> `start`) share the set; the outermost
+      # call owns its lifetime.
+      outer = Thread.current[:hammer_needs_ran].nil?
+      Thread.current[:hammer_needs_ran] ||= {}
+      Thread.current[:hammer_before_ran] ||= {}
+
       argv = argv.dup
       name = argv.shift
 
@@ -233,6 +283,9 @@ class Hammer
       Shell.print_error("unknown command: #{name}")
       print_help
       exit 1
+    ensure
+      Thread.current[:hammer_needs_ran] = nil if outer
+      Thread.current[:hammer_before_ran] = nil if outer
     end
 
     # Find a command by canonical name or alt within this class.
@@ -309,6 +362,8 @@ class Hammer
       positional, opts = Parser.new(cmd.options).parse(argv)
       opts[:args] = positional
       instance = new
+      run_before_hooks(instance, opts)
+      run_needs(cmd)
       instance.instance_exec(opts, &cmd.handler)
     rescue Parser::Error => e
       Shell.print_error(e.message)
@@ -321,6 +376,33 @@ class Hammer
       exit 1
     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.
+    def run_before_hooks(instance, opts)
+      ran = Thread.current[:hammer_before_ran] ||= {}
+      ancestor_chain.each do |klass|
+        next if ran[klass.object_id]
+        ran[klass.object_id] = true
+        klass.before_hooks.each { |hook| instance.instance_exec(opts, &hook) }
+      end
+    end
+
+    # Dispatch a command's declared `needs` through the root class, with
+    # per-invocation dedupe. Prereqs run with default options (no argv).
+    def run_needs(cmd)
+      return if cmd.needs.empty?
+      ran = Thread.current[:hammer_needs_ran] ||= {}
+      cmd.needs.each do |path|
+        key = path.to_s
+        next if ran[key]
+        ran[key] = true
+        target, = root.resolve(key)
+        raise Error, "needs: unknown command '#{key}' in #{cmd.name}" unless target
+        root.start([key])
+      end
+    end
+
     def help_requested?(argv)
       stop = argv.index('--')
       scan = stop ? argv[0...stop] : argv
@@ -337,15 +419,15 @@ class Hammer
         return
       end
 
-      Shell.say "Usage: #{program_name} COMMAND [ARGS]", :cyan, bold: true
-      Shell.say
+      Shell.say "Usage: #{program_name} COMMAND [ARGS]", :cyan
+      Shell.say ''
       print_command_list(self)
       print_footer
     end
 
     def print_namespace_help(prefix, ns)
-      Shell.say "Usage: #{program_name} #{prefix}:COMMAND [ARGS]", :cyan, bold: true
-      Shell.say
+      Shell.say "Usage: #{program_name} #{prefix}:COMMAND [ARGS]", :cyan
+      Shell.say ''
       print_command_list(ns, prefix)
       print_footer
     end
@@ -353,13 +435,16 @@ class Hammer
     HOMEPAGE ||= 'https://github.com/dux/hammer'.freeze
 
     def print_footer
-      Shell.say
+      Shell.say ''
       Shell.say "powered by hammer - #{HOMEPAGE}", :gray
     end
 
     def print_command_list(klass, prefix = nil)
       rows = []
-      klass.each_command(prefix) { |full, c| rows << [full, c] }
+      # Commands without a `desc` are hidden from listings but still
+      # dispatchable + `hammer_*`-callable - useful for private helpers
+      # invoked from `before` hooks or other commands (e.g. `:env`, `:app`).
+      klass.each_command(prefix) { |full, c| rows << [full, c] unless c.desc.empty? }
       return if rows.empty?
 
       # group by "section" = everything between the view prefix and the
@@ -422,19 +507,19 @@ class Hammer
 
     def print_command_help(cmd, full = nil)
       full ||= cmd.name
-      Shell.say "Usage: #{program_name} #{full}#{usage_signature(cmd)}", :cyan, bold: true
+      Shell.say "Usage: #{program_name} #{full}#{usage_signature(cmd)}", :cyan
       cmd.desc.each_line do |line|
         stripped = line.chomp
         Shell.say(stripped.empty? ? '' : "  #{stripped}")
       end unless cmd.desc.empty?
       Shell.say "  alias: #{cmd.alts.join(', ')}" unless cmd.alts.empty?
       unless cmd.options.empty?
-        Shell.say
+        Shell.say ''
         Shell.say 'Options:', :yellow
         cmd.options.each { |o| Shell.say "  #{o.usage}" }
       end
       unless cmd.examples.empty?
-        Shell.say
+        Shell.say ''
         Shell.say 'Examples:', :yellow
         cmd.examples.each { |e| Shell.say "  #{program_name} #{e}" }
       end
@@ -465,9 +550,21 @@ class Hammer
 
   # Define and run a CLI inline. Inside the block use `program`,
   # `define :name do ... end`, and `namespace`.
+  #
+  # Without a block: load ./Hammerfile if it exists, otherwise
+  # auto-discover *_hammer.rb under Dir.pwd, then dispatch ARGV.
   def self.run(argv = ARGV, &block)
     klass = Class.new(Hammer)
-    Builder.new(klass).instance_eval(&block)
+    if block
+      Builder.new(klass).instance_eval(&block)
+    else
+      hf = File.join(Dir.pwd, 'Hammerfile')
+      if File.file?(hf)
+        Builder.new(klass).instance_eval(File.read(hf), hf)
+      else
+        klass.loader.load(Dir.pwd, [], auto: true)
+      end
+    end
     klass.start(argv)
   end
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: lux-hammer
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.2.1
 platform: ruby
 authors:
 - Dino Reic