lux-hammer 0.2.3 → 0.2.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ae2c5c9dbcd3b17941440e327e04e84dbffaec7209e4ce15b205cf83525b3724
-  data.tar.gz: 516eb4a4cb0f8f02f489eb00d2e4500cfe70f600eaebe192fb1749c81fe37074
+  metadata.gz: 7007c5628c3466147f7776a2de86832fa8737623ef7d91c8c4dc4a4b3db7e557
+  data.tar.gz: 38d2781742e9cb9d8d12c22b3e8c416fe9f26901a7ef0bed678b206f872a9468
 SHA512:
-  metadata.gz: d922e58738cb3afc95c54864fc79d9a6ec556e3634a94f258711652abf220ba7f436e1d0f0cf24f48ba9c6372af22339d8377b491c9de93f708e19a7ca13692d
-  data.tar.gz: 6ad385997b87bf70ba58ec3ae6d701b3717d5e9584ef00aae29ebeb5c9b3666a39f6032277e275987f6de94161809767eeb838e288718fda09287327009756b6
+  metadata.gz: d3dd10a43530fd33c1535ea38086eb3a86ce8d3750e3f79acb765b390b667ab70048bda841e3ab3959effcc1438aa0557e07bfd7f24d727d64a8e963a3ed8b6c
+  data.tar.gz: e976dc67d490f64c44044fab9dcad7e2b5431570eefdada070feb2689daba6fea8af46572ba223a6f801c881917ff522f519d08cf19218bd530ac438f91d4759

data/.version

@@ -1 +1 @@
-0.2.3
+0.2.4

data/README.md

@@ -4,11 +4,11 @@ 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.
+Drop a `Hammerfile`, run `hammer`, ship. AI LLM-s love `hammer`.
 
 ```ruby
 namespace :db do                          # Rake-style colon paths
-  define :migrate do                      # Joshua-style define block
+  task :migrate do                      # Joshua-style task block
     desc 'Run pending migrations'
     opt :pretend, type: :boolean, alias: :p   # Thor-style typed opts
     proc do |o|
@@ -40,7 +40,7 @@ migrating pretend=true
   that most CLIs never reach for.
 
 * **From [Joshua](https://github.com/dux/joshua)** we took the
-  *`define :name do ... end` block DSL* - declarative metadata up
+  *`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".
@@ -67,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'}"
@@ -115,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
@@ -159,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
@@ -173,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
@@ -371,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| ... }
@@ -403,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 }
@@ -435,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
@@ -453,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
@@ -470,13 +472,13 @@ before { Dotenv.load }                  # runs before every command
 
 namespace :db do
   before { hammer :env }                # runs before every db:* command
-  define :migrate do
+  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` /
@@ -488,13 +490,13 @@ A command declared without a `desc` is **hidden from help listings**
 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
+  task :migrate do
     desc 'Run migrations'
     proc { |_| ... }
   end
@@ -509,17 +511,17 @@ end
 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
@@ -542,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
@@ -558,7 +560,7 @@ 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'
@@ -729,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}" }
@@ -739,7 +741,7 @@ 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
@@ -777,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`.
 
@@ -801,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|
@@ -845,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'
@@ -860,7 +862,7 @@ 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
@@ -875,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'
@@ -888,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
@@ -898,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
@@ -968,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}"
@@ -1006,7 +1008,7 @@ 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) |

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,7 +11,7 @@ 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
@@ -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,11 +158,11 @@ 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)
@@ -189,7 +189,7 @@ class Hammer
     #   before { |opts| Dotenv.load }
     #   namespace :db do
     #     before { hammer :env }
-    #     define :migrate do ... end
+    #     task :migrate do ... end
     #   end
     def before(&block)
       before_hooks << block
@@ -300,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
 
@@ -429,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
@@ -548,7 +584,7 @@ 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
@@ -564,7 +600,7 @@ class Hammer
   # ----- 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.
@@ -606,7 +642,7 @@ class Hammer
       Shell.say "create one - example:"
       puts
       Shell.say <<~RUBY
-        define :hello do
+        task :hello do
           desc 'say hello'
           proc do |opts|
             say.green "hello \#{opts[:args].first || 'world'}"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: lux-hammer
 version: !ruby/object:Gem::Version
-  version: 0.2.3
+  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: []