lux-hammer 0.2.2 → 0.2.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9b973a2becedf10ed4247fce46d195f07619c6f6b9bf56f41464b57764733716
-  data.tar.gz: a1ffdc8fa9b19f47599a3e930181fa1972095872db4f92740308cf393090bfcd
+  metadata.gz: ae2c5c9dbcd3b17941440e327e04e84dbffaec7209e4ce15b205cf83525b3724
+  data.tar.gz: 516eb4a4cb0f8f02f489eb00d2e4500cfe70f600eaebe192fb1749c81fe37074
 SHA512:
-  metadata.gz: 55e093ed6cc2ed08349fdfd9296360153b2d0cb4763b57546e4e9453657e0da7e74608179b70946d6600499624b0cac1c57017208a91143d3eba6917a1cef976
-  data.tar.gz: 3401f9c5defba4419e40c571cfcab4869ceb408dbcf8a88d9bab98aea2760ad810ceee02feaa31f78b661849e88b1ecb7c5e63ad3e930ed3baa371637d15f20b
+  metadata.gz: d922e58738cb3afc95c54864fc79d9a6ec556e3634a94f258711652abf220ba7f436e1d0f0cf24f48ba9c6372af22339d8377b491c9de93f708e19a7ca13692d
+  data.tar.gz: 6ad385997b87bf70ba58ec3ae6d701b3717d5e9584ef00aae29ebeb5c9b3666a39f6032277e275987f6de94161809767eeb838e288718fda09287327009756b6

data/.version

@@ -1 +1 @@
-0.2.2
+0.2.3

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.
+
+```ruby
+namespace :db do                          # Rake-style colon paths
+  define :migrate do                      # Joshua-style define 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
+  *`define :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
 
@@ -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
@@ -426,7 +469,7 @@ 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
+  before { hammer :env }                # runs before every db:* command
   define :migrate do
     proc { |opts| ... }                 # no boilerplate require inside
   end
@@ -442,7 +485,7 @@ 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
@@ -450,7 +493,7 @@ define :env do
 end
 
 namespace :db do
-  before { hammer_env }                 # call it from a hook
+  before { hammer :env }                # call it from a hook
   define :migrate do
     desc 'Run migrations'
     proc { |_| ... }
@@ -459,7 +502,7 @@ 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`)
 
@@ -483,7 +526,7 @@ 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 +534,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`)
@@ -509,7 +552,7 @@ 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:
@@ -517,28 +560,54 @@ invoke other commands without re-shelling out:
 ```ruby
 define :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
@@ -673,7 +742,7 @@ end
 define :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
@@ -798,7 +867,7 @@ define :deploy do
   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
@@ -909,7 +978,7 @@ class MyCli < Hammer
 end
 
 MyCli.start(ARGV)         # or:
-MyCli.hammer_greet('dino', loud: true)
+MyCli.hammer :greet, loud: true
 ```
 
 ## Development
@@ -941,7 +1010,7 @@ few small things that have been bugging me about both for years.
 | 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 +1024,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 +1040,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/lux-hammer.rb

@@ -17,7 +17,7 @@ require_relative 'hammer/command_builder'
 #       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
@@ -168,7 +168,7 @@ class Hammer
     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,7 +188,7 @@ class Hammer
     #
     #   before { |opts| Dotenv.load }
     #   namespace :db do
-    #     before { hammer_env }
+    #     before { hammer :env }
     #     define :migrate do ... end
     #   end
     def before(&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
 
@@ -283,11 +309,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 +338,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.
+    #
+    #   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)
     #
-    # 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|
+    # 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 +361,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)
@@ -442,7 +462,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?
@@ -530,20 +550,15 @@ class Hammer
   #
   #   define :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 -----------------------------------------------------
@@ -575,11 +590,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
           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.3
 platform: ruby
 authors:
 - Dino Reic