lux-hammer 0.3.8 → 0.3.10

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 64f8d2c7864047c17b42187e610ac14e93982a5ff1bd8dc6187a35670f67e432
-  data.tar.gz: 07b7014dcdfe70c48c293e7e18ce05475dcd565ee2c66310afa0c3a16d371f02
+  metadata.gz: 81af43fc44619384d2b62f58e7d3178a1b6edb22cbb1ef4e836b73e2ee469913
+  data.tar.gz: 47d012b5e54d1e8df3441de01eeaee3e3267f71c4ac8545b80f413d419bd3fc6
 SHA512:
-  metadata.gz: f1f4515e1340b132865081e4ff4118789540fd2c7c880d2ec42330d174e6f41f88b5355f40727207fa0320811bdba6f134d70a81604760221e2189be6cd73b7e
-  data.tar.gz: f43b40bd53e03f3c2a4ad04f5e8a886863c038b79f2cf18e39f96eb8e09bb3e8dfaa3c5a6610fc0acaee8f76c6a31860a0dc10f4a181c80fbc8ee64e5a45d32b
+  metadata.gz: d1dd7d495b96a6f7023601427dadcd492e593934c6407eb48dcb7c53fea26e33ea44ec40ef3a69856199fa75dd9d6278a8d32b14cbd4733b692dbbfe662f97ee
+  data.tar.gz: 2a9b223844fd645a79403c653a2bf25be28ba5654eef8562738b2f3768b0a72bddfd8b5ceb3dfe68ac7c583ecaaefc18fcee4d64f3f47964a93ff8f12b0fb586

data/.version

@@ -1 +1 @@
-0.3.8
+0.3.10

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/hammer/parser.rb

@@ -63,7 +63,11 @@ class Hammer
       @options.each do |opt|
         break if positional.empty?
         next if opt.boolean? || values.key?(opt.name)
-        values[opt.name] = opt.cast(positional.shift)
+        if opt.type == :array
+          values[opt.name] = opt.cast(positional.shift(positional.size))
+        else
+          values[opt.name] = opt.cast(positional.shift)
+        end
       end
 
       @options.each do |opt|

data/lib/hammer/shell.rb

@@ -31,8 +31,8 @@ class Hammer
 
     # `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?
+    def say(text = :_say_no_arg, color = nil)
+      return SayProxy.new if text == :_say_no_arg
       puts paint(text, color)
     end
 
@@ -116,9 +116,9 @@ class Hammer
               $stdout.print "\e[#{items.size}A\r\e[J"
               $stdout.print "#{paint("> #{items[selected]}", :green)}\r\n"
               return selected
-            when "\x03", 'q' # Ctrl-C, q
+            when "\x03" # Ctrl-C
               $stdout.print "\e[#{items.size}A\r\e[J"
-              return nil
+              raise Interrupt
             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 == '['

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
@@ -168,6 +169,7 @@ class Hammer
         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
@@ -414,6 +416,13 @@ class Hammer
       run_command(cmd, argv, full: name, quiet: true)
     end
 
+    # True when -h or --help appears in argv before a `--` stop-marker.
+    def help_requested?(argv)
+      stop = argv.index('--')
+      scan = stop ? argv[0...stop] : argv
+      scan.include?('-h') || scan.include?('--help')
+    end
+
     public
 
     # Find a command by canonical name or alt within this class. Falls
@@ -605,30 +614,26 @@ class Hammer
       end
     end
 
-    def help_requested?(argv)
-      stop = argv.index('--')
-      scan = stop ? argv[0...stop] : argv
-      scan.include?('-h') || scan.include?('--help')
-    end
+    public
 
     # `extended: true` is the verbose `help` / `-h` / `--help` form -
     # appends global flags, the GitHub footer, and (for the hammer binary)
     # a Hammerfile example. Bare invocation passes `extended: false` so
     # the no-args output stays a clean command listing.
-    def print_help(target = nil, full: false, extended: false)
+    def print_help(target = nil, expanded: false, extended: false)
       if target
         # `help ns:` is equivalent to `ns:` - namespace listing.
         if target.end_with?(':') && target != ':'
           bare = target.chomp(':')
           ns, canonical = resolve_namespace(bare)
-          return print_namespace_help(canonical, ns, extended: extended) if ns
+          return print_namespace_help(canonical, ns) if ns
           Shell.print_error("unknown: #{target}")
           return
         end
         cmd, _, canonical = resolve(target)
         return print_command_help(cmd, canonical) if cmd
         ns, canonical = resolve_namespace(target)
-        return print_namespace_help(canonical, ns, full: full, extended: extended) if ns
+        return print_namespace_help(canonical, ns, expanded: expanded) if ns
         Shell.print_error("unknown: #{target}")
         return
       end
@@ -639,7 +644,7 @@ class Hammer
         Shell.say ''
         @app_desc.each_line { |l| Shell.say "  #{l.chomp}" }
       end
-      if full
+      if expanded
         each_command { |path, c| print_full_block(path, c) unless c.desc.empty? }
       else
         Shell.say ''
@@ -670,10 +675,9 @@ class Hammer
 
     # `extended:` is accepted for parity with `print_help` but intentionally
     # not used here - the global-flags / Hammerfile-example / footer block
-    # is root-help-only. A namespace listing is just the commands under
-    # that prefix; tool-meta noise (Recipes: section) is reserved for
-    # `hammer --help` at the top level.
-    def print_namespace_help(prefix, ns, full: false, extended: false)
+    # is root-help-only. `expanded:` is also accepted for parity; a namespace
+    # listing is always the compact command list.
+    def print_namespace_help(prefix, ns, expanded: false, extended: false)
       Shell.say "Usage: #{program_name} #{prefix}:COMMAND [ARGS]", :cyan
       rows = []
       sibling = find_namespace_sibling(prefix)
@@ -989,6 +993,17 @@ class Hammer
     argv = argv.dup
     force_system = !!argv.delete('--system')
 
+    # Shebang invocation: `hammer /path/to/script ...args` (kernel passes
+    # the script path as argv[0] for `#!/usr/bin/env hammer` files).
+    # Treat the script as a self-contained CLI: no Hammerfile lookup, no
+    # chdir (commands run in the caller's cwd), no `hammer`-binary
+    # built-ins/banners. Detection requires a `#!`+`hammer` first line so
+    # task names that happen to be paths don't get hijacked.
+    if (script = shebang_script(argv.first))
+      argv.shift
+      return run_shebang(script, argv)
+    end
+
     path = force_system ? nil : find_hammerfile(Dir.pwd)
     unless path
       # No Hammerfile (or --system) - all built-ins are reachable. Bare
@@ -1058,6 +1073,33 @@ class Hammer
     klass.start(argv)
   end
 
+  # Returns the script path if `arg` looks like a shebang script that
+  # delegates to hammer (first line starts with `#!` and mentions
+  # `hammer`). Returns nil otherwise. Used by `cli` to detect
+  # `#!/usr/bin/env hammer` invocations where the kernel passes the
+  # script path as argv[0].
+  def self.shebang_script(arg)
+    return nil unless arg
+    return nil if arg.start_with?('-')
+    return nil unless File.file?(arg) && File.readable?(arg)
+    head = File.open(arg, &:gets).to_s
+    return nil unless head.start_with?('#!') && head.include?('hammer')
+    arg
+  end
+
+  # Evaluate a shebang script as a self-contained CLI. Mirrors `recipe`
+  # semantics: no chdir, no `@hammer_binary` flag, no `register_core`
+  # built-ins (so the script's `--help` shows only what it defines).
+  # `program_name` is the script's basename so help reads "myscript foo"
+  # rather than "hammer foo" - works even when invoked via a symlink in
+  # PATH, since argv[0] is the path the user typed.
+  def self.run_shebang(path, argv)
+    klass = Class.new(Hammer)
+    klass.instance_variable_set(:@program_name, File.basename(path))
+    Builder.new(klass).evaluate(File.read(path), path)
+    klass.start(argv)
+  end
+
   # True if argv goes through a built-in dispatch path (`:default` or
   # `:help`) - meaning bare `hammer`, leading-flag invocations like
   # `hammer -h`, or explicit help requests. These don't need a project

data/recipes/git-helper.rb

@@ -1,4 +1,6 @@
+#!/usr/bin/env hammer
 # desc: work with git (commit, push, pull, rebase, branch, redate, ...)
+# executable: chmod +x this file and run directly, or symlink into PATH
 
 desc <<~TXT
   Git helper. Short aliases over common `git` workflows.

data/recipes/llm.rb

@@ -1,4 +1,6 @@
+#!/usr/bin/env hammer
 # desc: personal LLM utility CLI (memory store, prompt-token expander, ...)
+# executable: chmod +x this file and run directly, or symlink into PATH
 
 desc <<~TXT
   llm - personal LLM utility CLI
@@ -54,6 +56,7 @@ namespace :memory do
     end
     [meta, body.to_s.sub(/\A\n+/, '')]
   end
+
   task :list do
     desc 'List stored memories with type and one-line description'
     example 'llm memory list'

data/recipes/srt.rb

@@ -1,4 +1,6 @@
+#!/usr/bin/env hammer
 # desc: Local SRT extraction via whisper.cpp
+# executable: chmod +x this file and run directly, or symlink into PATH
 
 desc <<~TXT
   Local subtitle extraction with whisper.cpp.

metadata

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