lux-hammer 0.3.9 → 0.3.12

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 60fa663d47e0d1d68790c40125c1594ae0152d99695cd57fe1d86294b1a5c348
-  data.tar.gz: 779a8291e200bff69a8c3b237662a88647a50071eb038f47fe695d547c805094
+  metadata.gz: 75362aef2908fdd2a3f4e32ab8c6ce7a4c4ae52fce795f5bca5437325a92da49
+  data.tar.gz: 0d318814ed2cdd0da35ca2b66e7637c62d5d2efece0cb24f60da1c5e02f4ad1f
 SHA512:
-  metadata.gz: 6b2114d72e01ee7aef8166a4881915d4c124e0cce67c6c9e5d680fb945750aa8b338fc7041332dcaf6d54fe15fac04cf3e85271e8cd75b5bc3126edacb30f827
-  data.tar.gz: 7f85fb830fae721e969e2d23e28a9c282c6655b8b9f29aa5c8dd15a9fa3e5f55eddcfa9a978d7605c37c1ca20c177b43c1475114f64f870e41e5993c56287854
+  metadata.gz: 64a8ce40bf7fc4986b6b0796c72fb9a8e9a13b2acb70c4aaa76cd68d5f68158bc9fbde7d5a0a5f3e586978b97f849f712b5addef336754b896e901f71c9feec2
+  data.tar.gz: 6f12a27b72098ff513ecc216ee8f2c6deb08e3c3a29cf4f1a7e9c6dfb7750a9b00ad13fe514f66fdda7b7a837b62e2526d1af04ca1af85deed1435e2d34b30a3

data/.version

@@ -1 +1 @@
-0.3.9
+0.3.12

data/AGENTS.md

@@ -98,10 +98,20 @@ At Hammerfile (block-DSL) top-level scope only:
 
 At class or `Hammerfile` scope:
 
-* `task :name do ... end`
+* `task :name do ... end` - redefining a task is last-write-wins. A
+  warning fires (and the entry is tagged `(redefined)` in help) **only**
+  when the task it clobbers was also defined inside the main app (cwd).
+  Overriding a task that came from outside - a framework default, plugin,
+  or gem (an absolute path outside cwd) - is treated as an intentional
+  override and stays silent. Locality is read off the location string:
+  `relativize_path` rewrites in-app absolutes to a `.`-relative form, so
+  anything still starting with `/` is external (see `app_local_location?`).
 * `namespace :name do ... end` - `:self` is reserved for the `hammer`
   binary's built-in namespace (see `lib/hammer/builtins.rb`). Defining
-  it from user code raises.
+  it from user code raises. Reopening a namespace **merges** (Rake-style):
+  the same `namespace :db` can be split across files / `load`ed fragments
+  and the blocks accumulate onto one subclass - no warning. Only a
+  duplicate *task* name warns (handled by `task`, last write wins).
 * `dotenv false` - opt out of auto `.env` / `.env.local` loading.
   Only meaningful from the `hammer` binary (`Hammer.cli`); the load
   happens after Hammerfile evaluation, before dispatch. Shell-set vars

data/README.md

@@ -946,6 +946,41 @@ Hammer.run ARGV do
 end
 ```
 
+### `#!/usr/bin/env hammer` (single-file scripts)
+
+For a one-off CLI that lives as a single executable file, point the
+shebang straight at `hammer` - no `require`, no boilerplate:
+
+```ruby
+#!/usr/bin/env hammer
+# desc: tiny greeter
+
+task :hello do
+  desc 'say hi'
+  opt :loud, type: :boolean, alias: :l
+  proc do |opts|
+    msg = "hello #{opts[:args].first || 'world'}"
+    say.cyan(opts[:loud] ? msg.upcase : msg)
+  end
+end
+```
+
+```sh
+$ chmod +x greet
+$ ./greet hello dino -l
+HELLO DINO
+$ ./greet --help
+Usage: greet COMMAND [ARGS]
+  ...
+```
+
+The file body is plain Hammerfile DSL (`task`, `namespace`, `before`,
+`load`). `hammer` detects the shebang, evaluates the script as a
+self-contained CLI, and uses the script's basename as the program name
+in help - so `./greet --help` reads "Usage: greet ..." rather than
+"Usage: hammer ...". The current working directory is left alone, so
+relative paths inside the script resolve where the user ran it.
+
 ## Complete example (every feature)
 
 ```ruby
@@ -1192,21 +1227,19 @@ few small things that have been bugging me about both for years.
 
 | | Thor | hammer |
 |-|-|-|
-| 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)` | `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) |
+| Command aliases | none (workarounds via `map`) | `alt :s, :srv` |
+| Pre-hooks | none built-in | `before { ... }` per scope, `needs :env` per command |
+| Chained dispatch | no | `hammer build + deploy + notify` |
 | 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:**
 
-* **One root constant.** Thor exposes `Thor`, `Thor::Group`, `Thor::Shell`,
-  `Thor::Actions` at the top level - Bundler had to vendor its own copy at
-  `Bundler::Thor` to avoid clashes. Hammer is just `Hammer`.
 * **The opts hash is just a Hash.** Symbol keys, always. No magic accessor
   object to remember, no string-vs-symbol confusion, no method_missing.
 * **Positional args fill opts in declaration order.** Thor either forces
@@ -1225,15 +1258,18 @@ few small things that have been bugging me about both for years.
 | | Rake | hammer |
 |-|-|-|
 | Primary use case | build/task automation with file deps | general CLIs |
-| Task file | `Rakefile` | `Hammerfile` |
+| Task file | `Rakefile` | `Hammerfile` (walks up parent dirs) |
 | 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 |
+| Prerequisites | `task :build => [:clean, :compile]` (declarative DAG) | `needs :clean, :compile` (declarative, deduped across `+` chains) |
+| Pre-hooks | none built-in | `before { ... }` scoped to root or namespace |
+| Chained dispatch | no (multi-task argv runs sequentially, no per-task flags) | `hammer build prod -v + db:migrate --pretend + deploy` |
 | 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) |
+| Shareable scripts | no | recipes (one-file CLIs installable as their own binary) |
 
 **What hammer does better and why:**
 

data/lib/hammer/command.rb

@@ -39,5 +39,34 @@ class Hammer
       name = name.to_s
       name == @name || @alts.include?(name)
     end
+
+    # Auto-assign a single-letter short alias (first letter of the opt
+    # name) to any opt that does not already declare one. Explicit
+    # aliases and `-h` are reserved first, so they always win. On
+    # collision the opt simply gets no short form - long flag still
+    # works. Idempotent.
+    def finalize!
+      return if @finalized
+      @finalized = true
+
+      claimed = ['-h']
+      @options.each do |o|
+        o.aliases.each { |a| claimed << a if short_flag?(a) }
+      end
+
+      @options.each do |o|
+        next if o.aliases.any? { |a| short_flag?(a) }
+        short = "-#{o.name.to_s[0]}"
+        next if claimed.include?(short)
+        o.aliases << short
+        claimed << short
+      end
+    end
+
+    private
+
+    def short_flag?(switch)
+      switch.length == 2 && switch.start_with?('-') && switch[1] != '-'
+    end
   end
 end

data/lib/lux-hammer.rb

@@ -96,6 +96,7 @@ class Hammer
       m = method_name
       arity = instance_method(method_name).arity
       cmd.handler = arity.zero? ? proc { send(m) } : proc { |opts| send(m, opts) }
+      cmd.finalize!
       commands[cmd.name] = cmd
 
       @pending_desc = nil
@@ -163,11 +164,16 @@ class Hammer
       end
       cmd.handler = handler
 
-      if (prev = commands[cmd.name])
+      # Only warn when overriding a task that was also defined inside the
+      # main app. Overriding one that came from outside - a framework
+      # default, plugin, or gem - is an intentional override, so stay quiet
+      # and don't tag it `(redefined)` in help.
+      if (prev = commands[cmd.name]) && app_local_location?(prev.location)
         cmd.prev_location = prev.location
         warn_redefinition('task', cmd.name, prev.location, cmd.location)
       end
 
+      cmd.finalize!
       commands[cmd.name] = cmd
 
       # `task` ignores pending class-level state, but clear it so a
@@ -188,28 +194,29 @@ class Hammer
     #     namespace :users do ... end
     #   end
     #
+    # Reopening a namespace merges: the same `namespace :db do ... end` can
+    # be split across files (Rake-style) and the blocks accumulate onto one
+    # subclass. Only a duplicate *task* name inside warns - that's handled
+    # by `task`. The namespace subclass is created lazily on first mention.
     def namespace(name, &block)
-      sub = Class.new(Hammer)
-      # Track the top-level CLI class so cross-invocation
-      # (`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
-      # tree can be collected and run outer -> inner before a command.
-      sub.instance_variable_set(:@parent, self)
-      # Share the parent's resolved program_name so help banners show
-      # "myapp ns:cmd" with the same prefix everywhere - and so the value
-      # captured pre-chdir (see `Hammer.cli`) survives into nested classes.
-      sub.instance_variable_set(:@program_name, program_name)
-      sub.instance_variable_set(:@location, source_location_of(block))
-      Hammer.with_target(sub) { sub.class_eval(&block) } if block
-
-      if (prev = @namespaces[name.to_s])
-        sub.instance_variable_set(:@prev_location, prev.instance_variable_get(:@location))
-        warn_redefinition('namespace', name.to_s, prev.instance_variable_get(:@location), sub.instance_variable_get(:@location))
-      end
+      sub = (@namespaces[name.to_s] ||= begin
+        ns = Class.new(Hammer)
+        # Track the top-level CLI class so cross-invocation
+        # (`hammer 'ns:cmd'`) from inside a namespaced command dispatches
+        # against the full tree, not just the current namespace.
+        ns.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.
+        ns.instance_variable_set(:@parent, self)
+        # Share the parent's resolved program_name so help banners show
+        # "myapp ns:cmd" with the same prefix everywhere - and so the value
+        # captured pre-chdir (see `Hammer.cli`) survives into nested classes.
+        ns.instance_variable_set(:@program_name, program_name)
+        ns.instance_variable_set(:@location, source_location_of(block))
+        ns
+      end)
 
-      @namespaces[name.to_s] = sub
+      Hammer.with_target(sub) { sub.class_eval(&block) } if block
     end
 
     # Register a hook to run before every command in this class (root or
@@ -250,7 +257,23 @@ class Hammer
     # built-in C-defined procs, eval'd blocks).
     def source_location_of(block)
       loc = block&.source_location
-      loc ? "#{loc[0]}:#{loc[1]}" : '(unknown)'
+      loc ? "#{relativize_path(loc[0])}:#{loc[1]}" : '(unknown)'
+    end
+
+    # Trim the cwd prefix off an absolute path so redefinition warnings
+    # read as `./lib/tasks/foo.rb` instead of a long absolute path. Paths
+    # outside cwd (framework / gem files) are left absolute.
+    def relativize_path(path)
+      prefix = "#{Dir.pwd}/"
+      path.start_with?(prefix) ? ".#{path[Dir.pwd.length..]}" : path
+    end
+
+    # True when a captured location lives inside the main app. relativize_path
+    # rewrites in-app absolute paths to a `.`-relative form, so anything still
+    # starting with "/" is an absolute path outside cwd - a framework, plugin,
+    # or gem file. Relative locations are already cwd-anchored, hence local.
+    def app_local_location?(loc)
+      !loc.to_s.start_with?('/')
     end
 
     # Emit a yellow [hammer] warning on stderr when a task/namespace is
@@ -733,7 +756,7 @@ class Hammer
 
     def print_footer
       Shell.say ''
-      Shell.say "powered by hammer - #{HOMEPAGE}", :gray
+      Shell.say "powered by hammer (v#{VERSION}) - #{HOMEPAGE}", :gray
     end
 
     # Hammerfile cheat-sheet shown under `hammer --help`. Same content

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: lux-hammer
 version: !ruby/object:Gem::Version
-  version: 0.3.9
+  version: 0.3.12
 platform: ruby
 authors:
 - Dino Reic
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-05-26 00:00:00.000000000 Z
+date: 2026-05-28 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: minitest