lux-hammer 0.2.2 → 0.2.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9b973a2becedf10ed4247fce46d195f07619c6f6b9bf56f41464b57764733716
-  data.tar.gz: a1ffdc8fa9b19f47599a3e930181fa1972095872db4f92740308cf393090bfcd
+  metadata.gz: 7007c5628c3466147f7776a2de86832fa8737623ef7d91c8c4dc4a4b3db7e557
+  data.tar.gz: 38d2781742e9cb9d8d12c22b3e8c416fe9f26901a7ef0bed678b206f872a9468
 SHA512:
-  metadata.gz: 55e093ed6cc2ed08349fdfd9296360153b2d0cb4763b57546e4e9453657e0da7e74608179b70946d6600499624b0cac1c57017208a91143d3eba6917a1cef976
-  data.tar.gz: 3401f9c5defba4419e40c571cfcab4869ceb408dbcf8a88d9bab98aea2760ad810ceee02feaa31f78b661849e88b1ecb7c5e63ad3e930ed3baa371637d15f20b
+  metadata.gz: d3dd10a43530fd33c1535ea38086eb3a86ce8d3750e3f79acb765b390b667ab70048bda841e3ab3959effcc1438aa0557e07bfd7f24d727d64a8e963a3ed8b6c
+  data.tar.gz: e976dc67d490f64c44044fab9dcad7e2b5431570eefdada070feb2689daba6fea8af46572ba223a6f801c881917ff522f519d08cf19218bd530ac438f91d4759

data/.version

@@ -1 +1 @@
-0.2.2
+0.2.4

data/README.md

@@ -1,9 +1,52 @@
 # hammer
 
-A modern CLI builder for Ruby. The good parts of
-[Rake](https://github.com/ruby/rake) and
-[Thor](https://github.com/rails/thor) without the cruft. Drop a
-`Hammerfile`, run `hammer`, ship.
+The bastard Frankenstein child of Rake, Thor, and Joshua. Sewn
+together from three good ideas, with the rest of each parent left on
+the cutting room floor.
+
+Drop a `Hammerfile`, run `hammer`, ship. AI LLM-s love `hammer`.
+
+```ruby
+namespace :db do                          # Rake-style colon paths
+  task :migrate do                      # Joshua-style task block
+    desc 'Run pending migrations'
+    opt :pretend, type: :boolean, alias: :p   # Thor-style typed opts
+    proc do |o|
+      say.green "migrating pretend=#{o[:pretend].inspect}"
+    end
+  end
+end
+```
+
+```sh
+$ hammer db:migrate --pretend
+migrating pretend=true
+```
+
+## The bloodline
+
+* **From [Rake](https://github.com/ruby/rake)** we took the *namespace
+  tree* and *task prereqs* - `db:users:list` colon paths, `needs :env`
+  dependencies, the one-file `Hammerfile` at the project root. Left on
+  the table: the build-system DNA (file/mtime tasks) and that
+  `task[a,b,c]` argument syntax nobody enjoys typing into a shell.
+
+* **From [Thor](https://github.com/rails/thor)** we took *real CLI
+  ergonomics* - typed options, defaults, aliases, required flags, and
+  generated `-h` help. Left on the table: the four-constant top-level
+  (`Thor`, `Thor::Group`, `Thor::Shell`, `Thor::Actions`), the
+  parallel method-params-vs-`method_option` arg systems, the
+  `HashWithIndifferentAccess`, and the file generator half of the gem
+  that most CLIs never reach for.
+
+* **From [Joshua](https://github.com/dux/joshua)** we took the
+  *`task :name do ... end` block DSL* - declarative metadata up
+  top, one `proc do |opts| ... end` at the bottom doing the work. No
+  `def`-and-`desc` split, no class required, no boilerplate between
+  "what this command is" and "what it does".
+
+The result: ~400 lines of code, zero runtime dependencies, and a file
+that reads top-to-bottom like a recipe.
 
 ## Install
 
@@ -24,7 +67,7 @@ This installs the `hammer` binary and exposes `require 'lux-hammer'`.
 Create a `Hammerfile` in your project root:
 
 ```ruby
-define :hello do
+task :hello do
   desc 'say hi'
   proc do |opts|
     say.green "hello #{opts[:args].first || 'world'}"
@@ -72,7 +115,7 @@ Hammer takes typed options, positional fill, and any common flag form:
 
 ```ruby
 # Hammerfile
-define :greet do
+task :greet do
   desc 'Say hello'
   opt :name
   opt :loud, type: :boolean, alias: :l
@@ -93,7 +136,7 @@ Rake::Task['db:migrate'].invoke('prod')
 ```
 ```ruby
 # hammer - reads like a normal Ruby method call
-hammer_db_migrate(env: 'prod')
+hammer 'db:migrate', env: 'prod'
 ```
 
 ### Thor: `desc` welded to a method, no aliases, two arg systems
@@ -116,7 +159,7 @@ end
 
 ```ruby
 # hammer - one arg system, real aliases, no usage string to maintain
-define :greet do
+task :greet do
   desc 'Say hello'
   alt :g
   opt :name
@@ -130,13 +173,13 @@ and there's one place to look for everything the command takes.
 
 ## The two styles
 
-### `define :name do ... end` (block DSL)
+### `task :name do ... end` (block DSL)
 
 The block's **last expression must be `proc do |opts| ... end`**. That
 proc is the handler. Everything before it is metadata.
 
 ```ruby
-define :build do
+task :build do
   desc    'Build the project'
   example 'build prod -v'
   opt :verbose, type: :boolean, alias: :v
@@ -328,7 +371,7 @@ Anything in ARGV without `-` / `--` fills the next un-set
 **non-boolean** opt, in declaration order:
 
 ```ruby
-define :deploy do
+task :deploy do
   opt :url
   opt :env, default: 'dev'
   proc { |opts| ... }
@@ -360,7 +403,7 @@ Always a `Hash` with **symbol keys**. Keys present:
 * `opts[:args]` - array of positional ARGV not absorbed by an opt
 
 ```ruby
-define :show do
+task :show do
   opt :env, default: 'dev'
   opt :loud, type: :boolean
   proc { |opts| p opts }
@@ -392,12 +435,12 @@ colon-paths from the root binary - just like `rake db:migrate`:
 
 ```ruby
 namespace :db do
-  define :migrate do
+  task :migrate do
     proc { |opts| ... }
   end
 
   namespace :users do
-    define :list do
+    task :list do
       proc { |opts| ... }
     end
   end
@@ -410,7 +453,9 @@ Then:
 hammer db:migrate
 hammer db:users:list
 hammer db                 # bare namespace lists everything under it
+hammer db:                # trailing colon: full per-task help for every command
 hammer db:migrate -h      # per-command help
+hammer :                  # trailing colon at root: full help for every command
 ```
 
 Namespaces nest to any depth. There is no per-level dispatch - the root
@@ -426,14 +471,14 @@ Hooks fire outer -> inner, then the command's handler:
 before { Dotenv.load }                  # runs before every command
 
 namespace :db do
-  before { hammer_env }                 # runs before every db:* command
-  define :migrate do
+  before { hammer :env }                # runs before every db:* command
+  task :migrate do
     proc { |opts| ... }                 # no boilerplate require inside
   end
 end
 ```
 
-`before` is intentionally not available inside `define` - the proc body
+`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.
 
 Pairs naturally with hidden commands (next section): keep `:env` /
@@ -442,16 +487,16 @@ Pairs naturally with hidden commands (next section): keep `:env` /
 ## Hidden commands (no `desc`)
 
 A command declared without a `desc` is **hidden from help listings**
-but stays fully dispatchable and `hammer_*`-callable:
+but stays fully dispatchable and `hammer`-callable:
 
 ```ruby
-define :env do
+task :env do
   proc { |_| require './config/env' }   # no desc -> hidden
 end
 
 namespace :db do
-  before { hammer_env }                 # call it from a hook
-  define :migrate do
+  before { hammer :env }                # call it from a hook
+  task :migrate do
     desc 'Run migrations'
     proc { |_| ... }
   end
@@ -459,31 +504,31 @@ end
 ```
 
 `hammer` and `hammer db` won't list `env`, but `hammer env`,
-`hammer_env` from another proc, and `before { hammer_env }` all work.
+`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
+task :env do
   proc { |_| require './config/env' }     # hidden helper
 end
 
-define :app do
+task :app do
   needs :env                              # runs `env` first
   desc 'start the app'
   proc { |opts| App.start }
 end
 
-define :deploy do
+task :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
+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
@@ -491,7 +536,7 @@ Each prereq fires **at most once per top-level invocation**, so if
 only once. Prereqs run with default options (no argv passed through).
 
 `needs` vs `before`:
-* `before { hammer_env }` - fires for *every* command in a scope.
+* `before { hammer :env }` - fires for *every* command in a scope.
 * `needs :env` - declared per command, deduped across the call chain.
 
 ## Command aliases (`alt`)
@@ -499,7 +544,7 @@ only once. Prereqs run with default options (no argv passed through).
 `alt :short_name` (or several) registers extra names for a command:
 
 ```ruby
-define :server do
+task :server do
   alt :s, :srv
   proc { |opts| ... }
 end
@@ -509,36 +554,62 @@ Then `hammer server`, `hammer s`, and `hammer srv` all dispatch to the
 same command. Alts work inside namespaces too: `alt :m` on `db:migrate`
 makes `db:m` resolve.
 
-## Cross-invocation (`hammer_*`)
+## Cross-invocation (`hammer`)
 
 From inside any command's proc - or from outside via the class - you can
 invoke other commands without re-shelling out:
 
 ```ruby
-define :deploy do
+task :deploy do
   proc do |opts|
-    hammer_build(env: 'prod', verbose: true)
-    hammer_db_migrate
+    hammer :build, env: 'prod', verbose: true
+    hammer 'db:migrate'
     say.green 'deployed'
   end
 end
 ```
 
-The mapping mirrors the CLI literally:
+Signature: `hammer(name, *args, **opts)`. `name` is a symbol for a
+single command or a colon-path string for namespaced commands. Trailing
+positionals become positional ARGV; kwargs become CLI flags:
 
-* `hammer_X_Y_Z` → command path `X:Y:Z` (underscores in the method
-  name become colons)
-* positional args → positional ARGV
+* `hammer :foo` → `foo`
+* `hammer 'db:users:list'` → `db:users:list`
+* `hammer :evaluate, 'puts 42'` → `evaluate "puts 42"` (positional ARGV)
 * `verbose: true` → `--verbose`
-* `no_cache: true` → `--no-cache` (just the same rule - underscores in
-  the kwarg key become dashes)
+* `no_cache: true` → `--no-cache` (underscores in the key become dashes)
 * `dry_run: true` → `--dry-run`
 * `env: 'prod'` → `--env=prod`
 * `anything: false` → skipped (no-op; use `no_x: true` to negate)
 
-`MyCli.hammer_db_users_list("a", verbose: true)` also works at the
+`MyCli.hammer 'db:users:list', verbose: true` also works at the
 class level, useful for tests and scripting.
 
+## Chained dispatch (`+`)
+
+Run several commands in one shot, Rake-style, using a bare `+` token
+as the separator:
+
+```sh
+hammer build + deploy + notify
+hammer build prod -v + db:migrate --pretend + deploy --url=https://x.com
+```
+
+Each segment is parsed and dispatched independently - its own opts,
+its own positional args. `needs` prereqs dedupe across the whole
+chain, so a shared `:env` step runs once even if every chained command
+declares `needs :env`.
+
+A `+` only acts as a separator when it arrives as its own argv token.
+Quoting protects it: `--foo="a + b"` reaches the parser as a single
+token and is left alone. To pass a literal `+` as a positional, double
+it - `++` unescapes to a single `+`:
+
+```sh
+hammer echo ++ x          # echo gets positional args ["+", "x"]
+hammer echo + bar         # runs echo, then runs bar
+```
+
 ## Shell helpers
 
 These are mixed into every handler (and also live on `Hammer::Shell` for
@@ -660,7 +731,7 @@ load auto: true              # recursive scan for *_hammer.rb from here
 ```ruby
 # tasks/db_hammer.rb
 namespace :db do
-  define :migrate do
+  task :migrate do
     desc 'Run pending migrations'
     opt :pretend, type: :boolean, alias: :p
     proc { |o| say.green "migrating pretend=#{o[:pretend].inspect}" }
@@ -670,10 +741,10 @@ end
 
 ```ruby
 # tasks/deploy_hammer.rb
-define :deploy do
+task :deploy do
   desc 'Deploy to prod'
   proc do |_|
-    hammer_db_migrate        # cross-file invocation just works
+    hammer 'db:migrate'      # cross-file invocation just works
     say.cyan 'deployed'
   end
 end
@@ -708,7 +779,7 @@ hidden directory.
 ### Fragment shape
 
 A `*_hammer.rb` file is a **block-DSL fragment** - same surface as a
-`Hammerfile`: `define`, `namespace`, and nested `load`. Not a class
+`Hammerfile`: `task`, `namespace`, and nested `load`. Not a class
 re-open. If you want to extend a `Hammer` subclass in the classic
 `desc` + `def` style across files, use plain `require_relative`.
 
@@ -732,7 +803,7 @@ Same shape as a Hammerfile, just inline:
 require 'lux-hammer'
 
 Hammer.run(ARGV) do
-  define :hello do
+  task :hello do
     desc 'say hi'
     opt :loud, type: :boolean, alias: :l
     proc do |opts|
@@ -776,7 +847,7 @@ end
 
 ```ruby
 # Simple top-level command
-define :build do
+task :build do
   desc    'Build the project'
   example 'build prod -v'
   example 'build --env=staging'
@@ -791,14 +862,14 @@ define :build do
 end
 
 # Command that calls another command
-define :deploy do
+task :deploy do
   desc 'Deploy to URL'
   alt :ship
   opt :url, req: true
   opt :force, type: :boolean
 
   proc do |opts|
-    hammer_build(env: 'prod')
+    hammer :build, env: 'prod'
     exit 0 unless yes? "deploy to #{opts[:url]}?" unless opts[:force]
     say.yellow "deploying to #{opts[:url]}"
   end
@@ -806,7 +877,7 @@ end
 
 # Namespace with two levels of nesting
 namespace :db do
-  define :migrate do
+  task :migrate do
     desc 'Run pending migrations'
     alt :m
     example 'db:migrate 3 --pretend'
@@ -819,7 +890,7 @@ namespace :db do
   end
 
   namespace :users do
-    define :list do
+    task :list do
       desc 'List users'
       opt :role, default: 'all'
       opt :limit, type: :integer, default: 100
@@ -829,7 +900,7 @@ namespace :db do
       end
     end
 
-    define :create do
+    task :create do
       desc 'Create a user'
       opt :email, req: true
       opt :admin, type: :boolean
@@ -899,7 +970,7 @@ directly. Useful for embedding or testing:
 require 'lux-hammer'
 
 class MyCli < Hammer
-  define :greet do
+  task :greet do
     opt :loud, type: :boolean
     proc do |opts|
       msg = "hello #{opts[:args].first}"
@@ -909,7 +980,7 @@ class MyCli < Hammer
 end
 
 MyCli.start(ARGV)         # or:
-MyCli.hammer_greet('dino', loud: true)
+MyCli.hammer :greet, loud: true
 ```
 
 ## Development
@@ -937,11 +1008,11 @@ few small things that have been bugging me about both for years.
 | Lines of code | ~6,000 | ~400 |
 | Runtime deps | a few | zero |
 | Root constants | `Thor`, `Thor::Group`, `Thor::Shell`, `Thor::Actions`, ... | just `Hammer` |
-| Command DSL | `desc 'usage', 'help'` + `method_option` + `def name(arg)` | `define :name do ... proc do \|opts\| end end` (or classic `desc` + `def`) |
+| Command DSL | `desc 'usage', 'help'` + `method_option` + `def name(arg)` | `task :name do ... proc do \|opts\| end end` (or classic `desc` + `def`) |
 | Opts container | `Thor::CoreExt::HashWithIndifferentAccess` | plain `Hash` with symbol keys |
 | Positional args | method positional params + `method_option`, two parallel systems | declared-order opts fill from positional, single system |
 | Sub-namespaces | `register SubClass, 'name', '...'` (inheritance ceremony) | `namespace :name do ... end` (no classes needed) |
-| Cross-invoke | `invoke 'name', [args], opts` | `hammer_name(*args, **kwargs)` (looks like a method call) |
+| Cross-invoke | `invoke 'name', [args], opts` | `hammer :name, **opts` (looks like a method call) |
 | Inline CLI | class only | class DSL **or** `Hammer.run do ... end` block DSL **or** a `Hammerfile` |
 
 **What hammer does better and why:**
@@ -955,7 +1026,7 @@ few small things that have been bugging me about both for years.
   you into method params (which then clash with options) or makes you read
   `ARGV` yourself. Hammer just says: opts you declared come first, leftover
   goes to `opts[:args]`.
-* **Cross-invocation reads as Ruby.** `hammer_db_migrate(env: 'prod')`
+* **Cross-invocation reads as Ruby.** `hammer 'db:migrate', env: 'prod'`
   looks like a method call. Thor's `invoke('db:migrate', [], env: 'prod')`
   always feels like reflection.
 * **No generator complexity.** Thor's other half is file scaffolding and
@@ -971,8 +1042,8 @@ few small things that have been bugging me about both for years.
 | Namespacing | colon paths (`db:migrate`) | colon paths (`db:migrate`) - parity |
 | Per-task options | `task[a,b,c]` positional only | typed `opt`s with flags, aliases, defaults, required |
 | Help | `rake -T` (plain list) | bare `hammer` lists everything grouped by namespace; `hammer X -h` for per-command help with examples and defaults |
-| Cross-invoke | `Rake::Task['db:migrate'].invoke` | `hammer_db_migrate` |
-| Prerequisites | `task :build => [:clean, :compile]` (declarative DAG) | explicit - call `hammer_clean; hammer_compile` in the proc |
+| Cross-invoke | `Rake::Task['db:migrate'].invoke` | `hammer 'db:migrate'` |
+| Prerequisites | `task :build => [:clean, :compile]` (declarative DAG) | explicit - call `hammer :clean; hammer :compile` in the proc |
 | File tasks | yes (mtime-based) | no |
 | Aliases | none (workarounds via re-defined tasks) | `alt :short_name` |
 | Split across files | `import 'other.rake'` | `load auto: true` (or explicit paths/globs) |

data/lib/hammer/builder.rb

@@ -7,8 +7,8 @@ class Hammer
       @klass = klass
     end
 
-    def define(name, &block)
-      @klass.define(name, &block)
+    def task(name, &block)
+      @klass.task(name, &block)
     end
 
     def namespace(name, &block)

data/lib/hammer/command_builder.rb

@@ -1,5 +1,5 @@
 class Hammer
-  # Context object for `define :name do ... end` blocks. Exposes
+  # Context object for `task :name do ... end` blocks. Exposes
   # desc/example/opt/alt; the block's return value (a `proc do |opts|`)
   # becomes the command handler.
   class CommandBuilder

data/lib/lux-hammer.rb

@@ -11,13 +11,13 @@ require_relative 'hammer/command_builder'
 # Class DSL:
 #
 #   class MyCli < Hammer
-#     define :build do
+#     task :build do
 #       desc    'Build the project'
 #       example 'build -v --env=prod'
 #       opt :verbose, type: :boolean, alias: :v
 #       opt :env,     type: :string,  default: 'dev'
 #       proc do |opts|
-#         say "building #{opts[:env]} args=#{opts[:args].inspect}", :green
+#         say.green "building #{opts[:env]} args=#{opts[:args].inspect}"
 #       end
 #     end
 #   end
@@ -27,7 +27,7 @@ require_relative 'hammer/command_builder'
 # Block DSL is identical, just inside `Hammer.run`:
 #
 #   Hammer.run(ARGV) do
-#     define :hello do
+#     task :hello do
 #       desc 'Greet someone'
 #       opt :loud, type: :boolean, alias: :l
 #       proc do |opts|
@@ -124,17 +124,17 @@ class Hammer
     # return a Proc as its last expression. That proc is the handler and
     # receives a single `opts` hash with symbol keys; positional ARGV
     # lives at `opts[:args]`.
-    def define(name, &block)
+    def task(name, &block)
       cmd = Command.new(name: name.to_s)
       handler = CommandBuilder.new(cmd).instance_eval(&block)
       unless handler.is_a?(Proc)
         raise Error, <<~MSG
-          define(:#{name}) block must end with a `proc do |opts| ... end`.
+          task(:#{name}) block must end with a `proc do |opts| ... end`.
           The proc's return value is what becomes the command handler.
 
           Example:
 
-            define :#{name} do
+            task :#{name} do
               desc    'what it does'
               example '#{name} foo --env=prod'
               opt :env, default: 'dev'
@@ -148,7 +148,7 @@ class Hammer
       cmd.handler = handler
       commands[cmd.name] = cmd
 
-      # `define` ignores pending class-level state, but clear it so a
+      # `task` ignores pending class-level state, but clear it so a
       # later `def` doesn't accidentally consume stale metadata.
       @pending_desc = nil
       @pending_examples = []
@@ -158,17 +158,17 @@ class Hammer
     end
 
     # Open a namespace (group of commands). Everything inside the block
-    # (define, nested namespace, ...) belongs to that namespace, evaluated
+    # (task, nested namespace, ...) belongs to that namespace, evaluated
     # against an anonymous Hammer subclass.
     #
     #   namespace :db do
-    #     define :migrate do ... end
+    #     task :migrate do ... end
     #     namespace :users do ... end
     #   end
     def namespace(name, &block)
       sub = Class.new(Hammer)
       # Track the top-level CLI class so cross-invocation
-      # (`hammer_<colon_path>`) from inside a namespaced command dispatches
+      # (`hammer 'ns:cmd'`) 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
@@ -188,8 +188,8 @@ class Hammer
     #
     #   before { |opts| Dotenv.load }
     #   namespace :db do
-    #     before { hammer_env }
-    #     define :migrate do ... end
+    #     before { hammer :env }
+    #     task :migrate do ... end
     #   end
     def before(&block)
       before_hooks << block
@@ -257,15 +257,41 @@ class Hammer
     # Entry point. Parses ARGV, finds the right command, runs it.
     # Command names are Rake-style colon paths: "build", "db:migrate",
     # "db:users:list".
+    #
+    # Rake-style chained dispatch: `hammer build + deploy + notify`.
+    # A bare `+` argv token separates commands; `++` escapes to a literal
+    # `+` positional. Quoted shell args (`--foo="a + b"`) arrive as a
+    # single token and are not split.
     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.
+      # `needs` -> `hammer` -> `start`, or a `+` chain) 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] ||= {}
 
+      split_chain(argv).each { |seg| dispatch(seg) }
+    ensure
+      Thread.current[:hammer_needs_ran] = nil if outer
+      Thread.current[:hammer_before_ran] = nil if outer
+    end
+
+    private
+
+    # Split argv on bare `+` tokens; unescape `++` -> `+` within each
+    # segment. Returns [argv] when no chain operator is present.
+    def split_chain(argv)
+      return [argv] unless argv.include?('+') || argv.include?('++')
+      segs = argv.slice_when { |a, b| a == '+' || b == '+' }
+                 .map { |seg| seg.reject { |t| t == '+' } }
+                 .map { |seg| seg.map { |t| t == '++' ? '+' : t } }
+                 .reject(&:empty?)
+      segs.empty? ? [argv] : segs
+    end
+
+    # Run a single (already-split) command segment.
+    def dispatch(argv)
       argv = argv.dup
       name = argv.shift
 
@@ -274,6 +300,19 @@ class Hammer
         return print_help(target)
       end
 
+      # Trailing colon ("db:") -> expanded namespace listing with full
+      # per-command help on every task. Bare ":" expands the root.
+      if name.end_with?(':') && name != ':'
+        bare = name.chomp(':')
+        ns = resolve_namespace(bare)
+        return print_namespace_help(bare, ns, full: true) if ns
+        Shell.print_error("unknown namespace: #{bare}")
+        print_help
+        exit 1
+      elsif name == ':'
+        return print_help(nil, full: true)
+      end
+
       cmd, owner = resolve(name)
       return owner.run_command(cmd, argv, full: name) if cmd
 
@@ -283,11 +322,10 @@ 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
 
+    public
+
     # Find a command by canonical name or alt within this class.
     def find_command(name)
       commands[name.to_s] || commands.values.find { |c| c.matches?(name) }
@@ -313,23 +351,22 @@ class Hammer
       klass
     end
 
-    # MyCli.hammer_db_users_list("a", verbose: true) ->
-    # MyCli.start(["db:users:list", "a", "--verbose"])
+    # Programmatic dispatch by name. Useful for scripting and tests.
     #
-    # Useful for scripting and tests. Underscores in the method name map
-    # to colons; underscores in kwarg keys map to dashes in the flag.
-    def method_missing(name, *args, **kwargs, &block)
-      str = name.to_s
-      return super unless str.start_with?('hammer_')
-
-      path = str.sub(/^hammer_/, '').tr('_', ':')
-      argv = [path, *args.map(&:to_s)]
-      # kwarg key mirrors the CLI flag literally:
-      #   verbose: true       -> --verbose
-      #   no_cache: true      -> --no-cache  (just the general rule)
-      #   env: 'prod'         -> --env=prod
-      #   anything: false     -> skipped (no-op; use `no_x: true` to negate)
-      kwargs.each do |k, v|
+    #   MyCli.hammer :build                       -> start(["build"])
+    #   MyCli.hammer 'db:users:list'              -> start(["db:users:list"])
+    #   MyCli.hammer :eval, 'puts 42'             -> start(["eval", "puts 42"])
+    #   MyCli.hammer :build, env: 'prod'          -> start(["build", "--env=prod"])
+    #   MyCli.hammer :build, verbose: true        -> start(["build", "--verbose"])
+    #   MyCli.hammer :build, no_cache: true       -> start(["build", "--no-cache"])
+    #   MyCli.hammer :build, cache: false         -> skipped (no-op)
+    #
+    # Symbols are single-segment names; pass a string with colons for
+    # namespaced paths. Trailing positionals become positional ARGV.
+    # Underscores in option keys become dashes in flags.
+    def hammer(name, *args, **opts)
+      argv = [name.to_s, *args.map(&:to_s)]
+      opts.each do |k, v|
         next if v == false
         flag = "--#{k.to_s.tr('_', '-')}"
         argv << (v == true ? flag : "#{flag}=#{v}")
@@ -337,10 +374,6 @@ class Hammer
       start(argv)
     end
 
-    def respond_to_missing?(name, include_private = false)
-      name.to_s.start_with?('hammer_') || super
-    end
-
     # Yield [full_colon_path, Command] for every command in this class
     # and all nested namespaces.
     def each_command(prefix = nil, &block)
@@ -409,29 +442,52 @@ class Hammer
       scan.include?('-h') || scan.include?('--help')
     end
 
-    def print_help(target = nil)
+    def print_help(target = nil, full: false)
       if target
+        # `help ns:` is equivalent to `ns:` - expanded namespace listing.
+        if target.end_with?(':') && target != ':'
+          bare = target.chomp(':')
+          ns = resolve_namespace(bare)
+          return print_namespace_help(bare, ns, full: true) 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) if ns
+        return print_namespace_help(target, ns, full: full) if ns
         Shell.print_error("unknown: #{target}")
         return
       end
 
       Shell.say "Usage: #{program_name} COMMAND [ARGS]", :cyan
-      Shell.say ''
-      print_command_list(self)
+      if full
+        each_command { |path, c| print_full_block(path, c) unless c.desc.empty? }
+      else
+        Shell.say ''
+        print_command_list(self)
+      end
       print_footer
     end
 
-    def print_namespace_help(prefix, ns)
+    def print_namespace_help(prefix, ns, full: false)
       Shell.say "Usage: #{program_name} #{prefix}:COMMAND [ARGS]", :cyan
-      Shell.say ''
-      print_command_list(ns, prefix)
+      if full
+        ns.each_command(prefix) { |path, c| print_full_block(path, c) unless c.desc.empty? }
+      else
+        Shell.say ''
+        print_command_list(ns, prefix)
+      end
       print_footer
     end
 
+    # One "task block" for the expanded listing: blank line separator
+    # then the standard per-command help (usage + desc + options + examples).
+    def print_full_block(path, cmd)
+      Shell.say ''
+      print_command_help(cmd, path)
+    end
+
     HOMEPAGE ||= 'https://github.com/dux/hammer'.freeze
 
     def print_footer
@@ -442,7 +498,7 @@ class Hammer
     def print_command_list(klass, prefix = nil)
       rows = []
       # Commands without a `desc` are hidden from listings but still
-      # dispatchable + `hammer_*`-callable - useful for private helpers
+      # 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?
@@ -528,28 +584,23 @@ class Hammer
 
   # Inside a command's `proc do |opts| ... end`, call sibling commands:
   #
-  #   define :deploy do
+  #   task :deploy do
   #     proc do |opts|
-  #       hammer_build
-  #       hammer_db_migrate(pretend: true)
+  #       hammer :build
+  #       hammer 'db:migrate', pretend: true
   #     end
   #   end
-  def method_missing(name, *args, **kwargs, &block)
-    return super unless name.to_s.start_with?('hammer_')
-    # Dispatch from the root class so `hammer_a_b` resolves against the
-    # full colon path "a:b" even when called inside a namespaced command
-    # (where self.class would be the namespace subclass).
-    self.class.root.send(name, *args, **kwargs, &block)
-  end
-
-  def respond_to_missing?(name, include_private = false)
-    name.to_s.start_with?('hammer_') || super
+  #
+  # Dispatches from the root class so colon paths resolve against the
+  # full tree even when called from inside a namespaced command.
+  def hammer(name, *args, **opts)
+    self.class.root.hammer(name, *args, **opts)
   end
 
   # ----- block DSL -----------------------------------------------------
 
   # Define and run a CLI inline. Inside the block use
-  # `define :name do ... end`, `namespace`, and `load`.
+  # `task :name do ... end`, `namespace`, and `load`.
   #
   # Without a block: load ./Hammerfile if it exists, otherwise
   # auto-discover *_hammer.rb under Dir.pwd, then dispatch ARGV.
@@ -575,11 +626,27 @@ class Hammer
     path = find_hammerfile(Dir.pwd)
     unless path
       Shell.print_error "no Hammerfile found in #{Dir.pwd} or any parent directory"
+
+      # Heuristic: *.rb files referencing `Hammer.` are likely inline CLIs
+      # the user could promote into a Hammerfile.
+      excludes = %w[.git node_modules tmp vendor coverage dist build]
+                 .map { |d| "--exclude-dir=#{d}" }.join(' ')
+      candidates = `grep -rl --include='*.rb' #{excludes} 'Hammer\\.' . 2>/dev/null`
+                   .lines.map(&:strip).reject(&:empty?)
+      unless candidates.empty?
+        Shell.say "possible CLI implementation(s) - files referencing `Hammer.`:", :yellow
+        candidates.first(10).each { |f| Shell.say "  #{f.sub(%r{\A\./}, '')}" }
+        Shell.say ''
+      end
+
       Shell.say "create one - example:"
+      puts
       Shell.say <<~RUBY
-        define :hello do
+        task :hello do
           desc 'say hello'
-          proc { |opts| say "hello \#{opts[:args].first || 'world'}", :green }
+          proc do |opts|
+            say.green "hello \#{opts[:args].first || 'world'}"
+          end
         end
       RUBY
       exit 1

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: lux-hammer
 version: !ruby/object:Gem::Version
-  version: 0.2.2
+  version: 0.2.4
 platform: ruby
 authors:
 - Dino Reic
@@ -61,7 +61,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.8
+rubygems_version: 4.0.10
 specification_version: 4
 summary: Thor-inspired tiny CLI builder
 test_files: []