lux-hammer 0.3.12 → 0.3.13

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 75362aef2908fdd2a3f4e32ab8c6ce7a4c4ae52fce795f5bca5437325a92da49
-  data.tar.gz: 0d318814ed2cdd0da35ca2b66e7637c62d5d2efece0cb24f60da1c5e02f4ad1f
+  metadata.gz: 411174afd97cefbe9e7e3309c25233f465b9458ee0dc710e67077725658876c0
+  data.tar.gz: f4b64f7897fd8c67412fdbe418ad51b96eeac1ebb3e87ce9df5b97651a4a9ff6
 SHA512:
-  metadata.gz: 64a8ce40bf7fc4986b6b0796c72fb9a8e9a13b2acb70c4aaa76cd68d5f68158bc9fbde7d5a0a5f3e586978b97f849f712b5addef336754b896e901f71c9feec2
-  data.tar.gz: 6f12a27b72098ff513ecc216ee8f2c6deb08e3c3a29cf4f1a7e9c6dfb7750a9b00ad13fe514f66fdda7b7a837b62e2526d1af04ca1af85deed1435e2d34b30a3
+  metadata.gz: ba1364fcff70fefa529a2e7586ee33f7826b43ee7cd3ebd5e454f0bce82131b427cf320d85d8d911edc3a11762196de7db9964c6877959548eb4c6753e5ac063
+  data.tar.gz: 5b21c08ac766b1af02b1a0d49b7fb3129fffd94b0c13fd07c7a5995851c21447e6a437848f25ef30f364bfccb94f1bac51046630dbbd574aaa109a61a738e893

data/.version

@@ -1 +1 @@
-0.3.12
+0.3.13

data/AGENTS.md

@@ -156,17 +156,18 @@ Runtime cross-invocation:
   errors if none found anywhere up the tree (unless the invocation
   routes to a built-in - see `dispatches_to_builtin?` /
   `looks_like_builtin?`, true for bare invocation / leading flag /
-  explicit help / a built-in task name). After evaluating the
-  Hammerfile, registers the always-on core built-ins (`:default`,
-  `:help`, `:update`, `:agents`, `:version`) via
-  `Hammer::Builtins.register_core` - each guarded by
-  `unless commands.key?(...)` so a user-defined task wins silently.
-  No-project-only built-ins (`:recipes`, `:init`) are NOT registered
-  when a Hammerfile loaded - reach them with `--system`. The
-  `--system` flag is peeled off argv at the top and forces the
-  no-Hammerfile branch. Not part of the user-facing surface - don't
-  recommend it in examples; `Hammer.run` is what library users should
-  reach for.
+  explicit help / an `h:`-namespace path). After evaluating the
+  Hammerfile, registers the built-ins via `Hammer::Builtins.register`:
+  `:default` at the root (backs bare invocation, carries `--version`)
+  plus the `h:` namespace (`h:help`, `h:update`, `h:agents`,
+  `h:version`, `h:recipes`, `h:init`). The full set registers in every
+  context - living under `h:` means they can't collide with project
+  root tasks, so there's no core/no-project split. Each is guarded by
+  `unless commands.key?(...)` so a user who reopens `namespace :h` wins
+  silently. The `--system` flag is peeled off argv at the top and
+  forces the no-Hammerfile branch. Not part of the user-facing surface
+  - don't recommend it in examples; `Hammer.run` is what library users
+  should reach for.
 * `Hammer.recipe(name, argv = ARGV)` - entry for recipe stubs in PATH.
   Loads `<gem>/recipes/<name>.rb` (or its user-dir override), runs as
   a standalone CLI with `program_name = name`. No Hammerfile lookup,
@@ -239,45 +240,50 @@ explicit ADR-level discussion. Keys:
 
 ## Built-in tasks (user-overridable)
 
-`Hammer::Builtins` defines two registration entry points; both register
-**after** Hammerfile evaluation and skip each task when the user
-already defined it (`unless klass.commands.key?(name)` - no
-redefinition warning).
-
-* `register_core(klass)` - always called. Registers `:default`,
-  `:help`, `:update`, `:agents`, `:version`. These coexist with
-  Hammerfile tasks.
-* `register_no_project(klass)` - called only on the no-Hammerfile
-  branch of `Hammer.cli` (which `--system` also routes through).
-  Registers `:recipes` and `:init` - tasks that would collide too
-  easily with user tasks inside a project.
-
-No reserved namespace. Names like `:self`, `:recipes`, `:update` can
-all be defined freely in a Hammerfile; the built-ins yield.
+`Hammer::Builtins.register(klass)` is the single registration entry
+point. It runs **after** Hammerfile evaluation and skips each task when
+the user already defined it (`unless commands.key?(name)` - no
+redefinition warning). The same set registers in every context (project
+or bare binary): `:default` at the root, everything else under the
+reserved `h:` namespace.
+
+* Root: `:default` (hidden, carries `--version` / `-v`).
+* `h:` namespace: `h:help`, `h:update`, `h:agents`, `h:version`,
+  `h:recipes`, `h:init`.
+
+`h:` is the reserved built-in namespace - keeping the tool-meta commands
+there means they never collide with a project's root tasks, so there's
+no core/no-project split and no hidden-desc bookkeeping. Other names
+(`:self`, `:recipes` at the root, ...) stay free for Hammerfiles. The
+`h:` subclass is flagged `@builtin_namespace`, which prunes it from the
+compact listing - the built-ins are always dispatchable but only show
+(under an `h:` section) in the extended `--help` view.
 
 Task contracts:
 
-* `:default` - hidden (no desc). Just prints `self.class.root.print_help`
-  (brief). Fires for bare `hammer` and leading-flag invocations where
-  the first token starts with `-` and isn't `-h` / `--help` (see
+* `:default` - hidden (no desc), at the root. Prints
+  `self.class.root.print_help` (brief) and exposes a `--version` flag.
+  Fires for bare `hammer` and leading-flag invocations where the first
+  token starts with `-` and isn't `-h` / `--help` (see
   `Hammer.dispatch`). User overrides typically declare flag opts and
   fall through to `hammer :help` when none matched.
-* `:help` - has a desc, shows in listings. Calls
-  `self.class.root.print_help(opts[:args].first, extended: true)`.
-  Fires for `help` / `-h` / `--help` at the top level.
-* `:update` / `:agents` / `:version` - thin wrappers around
+* `h:help` - has a desc; shows in the `--help` listing. Calls
+  `self.class.root.print_help(opts[:args].first, extended: true)`. The
+  conventional `help` / `-h` / `--help` at the top level still reach it
+  (handled directly in `Hammer.dispatch`).
+* `h:update` / `h:agents` / `h:version` - thin wrappers around
   `Hammer.self_update` / `Hammer.print_ai_help` / `puts Hammer::VERSION`.
-* `:recipes` - all recipe-management actions on one task, picked via
+* `h:recipes` - all recipe-management actions on one task, picked via
   boolean opts: `--install [NAME [TARGET]]`, `--show NAME`,
   `--path NAME`, `--edit NAME`, `--run NAME [ARGS]` (use `--` to
   forward flags through). Bare invocation lists.
-* `:init` - writes `Hammer::STARTER_HAMMERFILE` to `./Hammerfile`;
+* `h:init` - writes `Hammer::STARTER_HAMMERFILE` to `./Hammerfile`;
   refuses if one exists.
 
-Both `:default` and `:help` are invoked via `run_command(cmd, argv,
-full: name, quiet: true)` - the gray `> prog cmd ...` banner is
-suppressed because the user didn't type `hammer default` /
-`hammer help` literally.
+The `:default` task and the `help` / `-h` / `--help` requests are
+invoked via `run_command(cmd, argv, full: name, quiet: true)` - the
+gray `> prog cmd ...` banner is suppressed because the user didn't type
+`hammer default` / `hammer h:help` literally.
 * Commands listed flat with colon paths, grouped by top-level namespace.
 * Bare namespace (`hammer db`) prints the same listing scoped to that
   namespace.

data/README.md

@@ -73,7 +73,7 @@ Clones into `~/.local/share/lux-hammer` (override with `LUX_HAMMER_DIR=`),
 builds the gem, and installs it. Re-run any time, or use:
 
 ```sh
-hammer update   # git pull main + rebuild + reinstall
+hammer h:update   # git pull main + rebuild + reinstall
 ```
 
 ## Quick start
@@ -537,41 +537,43 @@ end
 `hammer` and `hammer db` won't list `env`, but `hammer env`,
 `hammer :env` from another proc, and `before { hammer :env }` all work.
 
-## Built-in tasks (all overridable)
+## Built-in tasks
 
-The `hammer` binary auto-registers a small set of built-in tasks at
-the root of your CLI. Each one is guarded by `unless commands.key?` -
-defining your own `task :name` in a Hammerfile silently replaces the
-built-in.
+The `hammer` binary auto-registers a small set of built-in tasks. All
+the tool-meta commands live under the reserved `h:` namespace so they
+can never collide with your project's own root tasks. They register the
+same way with or without a Hammerfile and are always dispatchable, but
+to keep the bare listing focused on your project they only show up
+(under an `h:` section) in the extended `hammer --help` view.
 
-Always available (with or without a Hammerfile):
+Handled at the root (so the conventional invocations keep working):
 
 * `:default` - fires on bare `hammer` and on leading-flag invocations.
-  Hidden from listings. Just prints the brief help by default; override
-  to wire up your own global flags.
-* `:help` - `hammer help [TARGET]`, `hammer -h`, `hammer --help`. Prints
-  the extended help view; `TARGET` accepts a command path or a `ns:`
-  prefix.
-* `:update` - rebuild + reinstall lux-hammer from main.
-* `:agents` - dump AGENTS.md (AI-friendly Hammerfile authoring docs).
-* `:version` - print the lux-hammer version.
+  Hidden from listings. Prints the brief help by default and carries a
+  `--version` / `-v` flag; override to wire up your own global flags.
+* `hammer help [TARGET]`, `hammer -h`, `hammer --help` - prints the
+  extended help view; `TARGET` accepts a command path or a `ns:` prefix.
+  (Also available as `hammer h:help`.)
 
-Only when no Hammerfile is loaded (or `--system` is passed - see below):
+Under the `h:` namespace:
 
-* `:recipes` - list / install / show / edit recipes.
-* `:init` - write a starter Hammerfile in cwd (refuses if one exists).
+* `h:update` - rebuild + reinstall lux-hammer from main.
+* `h:agents` - dump AGENTS.md (AI-friendly Hammerfile authoring docs).
+* `h:version` - print the lux-hammer version.
+* `h:recipes` - list / install / show / edit recipes.
+* `h:init` - write a starter Hammerfile in cwd (refuses if one exists).
 
-These two are skipped inside a project so they don't shadow user tasks.
-To reach them from inside a project, pass `--system`:
+Each is guarded by `unless commands.key?` within the namespace, so you
+can override one by reopening `namespace :h` in your Hammerfile.
+
+`--system` forces the no-Hammerfile branch - the Hammerfile in the
+current tree (if any) isn't loaded for that invocation:
 
 ```sh
-hammer --system recipes              # list recipes from anywhere
-hammer --system recipes --install srt ~/bin/srt
+hammer --system h:recipes              # list recipes, ignoring any local Hammerfile
+hammer --system h:recipes --install srt ~/bin/srt
 ```
 
-`--system` forces the no-Hammerfile branch - the Hammerfile in the
-current tree (if any) isn't loaded for that invocation.
-
 Customize bare `hammer` by replacing `:default`:
 
 ```ruby
@@ -1106,20 +1108,21 @@ A **recipe** is a standalone Hammerfile-style script bundled inside the
 top-level binary in your `PATH` - so `srt` becomes a real command, not
 `hammer srt:shift`.
 
-Recipe management lives under the `recipes` task. From inside a
-project the task isn't registered (so it can't shadow user tasks);
-pass `--system` to reach it from anywhere.
+Recipe management lives under the `h:recipes` task, reachable from
+anywhere (inside a project the `h:` namespace can't shadow your root
+tasks). `--system` skips loading a local Hammerfile if you want a clean
+environment.
 
 Listing what's available:
 
 ```sh
-$ hammer recipes                    # from any non-project dir
-$ hammer --system recipes           # from inside a project
+$ hammer h:recipes                    # from any directory
+$ hammer --system h:recipes           # ignoring any local Hammerfile
 gem:
   srt  # Subtitle (.srt) toolkit - shift timestamps, show stats
-         [install: hammer recipes --install srt]
+         [install: hammer h:recipes --install srt]
   llm  # personal LLM utility CLI (memory store, prompt-token expander, ...)
-         [install: hammer recipes --install llm]
+         [install: hammer h:recipes --install llm]
 ```
 
 Installing one. With no TARGET, the stub is printed to stdout (you
@@ -1127,8 +1130,8 @@ redirect it yourself); with a TARGET path, lux-hammer writes the file
 and chmods +x in one step:
 
 ```sh
-$ hammer recipes --install srt ~/bin/srt    # write + chmod
-$ hammer recipes --install srt > ~/bin/srt && chmod +x ~/bin/srt
+$ hammer h:recipes --install srt ~/bin/srt    # write + chmod
+$ hammer h:recipes --install srt > ~/bin/srt && chmod +x ~/bin/srt
 $ srt --help
 Usage: srt COMMAND [ARGS]
 
@@ -1145,7 +1148,7 @@ so the recipe always runs the version currently in the gem.
 ### Authoring your own
 
 Drop a plain `.rb` file in `~/.config/hammer/recipes/`. The first
-`# desc: ...` comment is what shows in `hammer recipes`. The file body
+`# desc: ...` comment is what shows in `hammer h:recipes`. The file body
 uses the same DSL as a Hammerfile - `task`, `namespace`, `before`,
 `load`. Example `~/.config/hammer/recipes/json.rb`:
 
@@ -1165,22 +1168,22 @@ end
 Install it the same way:
 
 ```sh
-$ hammer recipes --install json ~/bin/json
+$ hammer h:recipes --install json ~/bin/json
 ```
 
 User-dir recipes override gem recipes with the same name, so you can
 fork without forking.
 
-### Other `recipes` actions
+### Other `h:recipes` actions
 
 ```sh
-hammer recipes                            # list all
-hammer recipes --install                  # interactive picker, then prints stub
-hammer recipes --show NAME                # cat the recipe source
-hammer recipes --path NAME                # absolute path
-hammer recipes --edit NAME                # open in $EDITOR (copies gem -> user dir first)
-hammer recipes --run  NAME [ARGS]         # run without installing its bin
-hammer recipes --run  NAME -- --help      # `--` forwards flags to the recipe
+hammer h:recipes                            # list all
+hammer h:recipes --install                  # interactive picker, then prints stub
+hammer h:recipes --show NAME                # cat the recipe source
+hammer h:recipes --path NAME                # absolute path
+hammer h:recipes --edit NAME                # open in $EDITOR (copies gem -> user dir first)
+hammer h:recipes --run  NAME [ARGS]         # run without installing its bin
+hammer h:recipes --run  NAME -- --help      # `--` forwards flags to the recipe
 ```
 
 ## Programmatic use

data/lib/hammer/builtins.rb

@@ -1,29 +1,36 @@
 class Hammer
-  # Built-in tasks of the `hammer` binary - all live at the root level
-  # (no reserved namespace). Two registration entry points:
-  #
-  # * register_core - tasks always available (subject to user override
-  #   via the `unless commands.key?(...)` guard): :default, :help,
-  #   :update, :agents, :version. These coexist with Hammerfile tasks.
-  #
-  # * register_no_project - tasks meaningful only when no Hammerfile is
-  #   loaded (or `--system` was passed): :recipes, :init. These would
-  #   collide too easily with user tasks if always registered, so the
-  #   Hammerfile branch skips them.
+  # Built-in tasks of the `hammer` binary. Everything but :default lives
+  # under the reserved `h:` namespace (e.g. `hammer h:update`,
+  # `hammer h:recipes`) so the built-ins never collide with a project's
+  # own root tasks. Only the bare `hammer` invocation and the
+  # `-h`/`--help`/`help` request are handled at root - bare fires
+  # :default, which also carries the `--version` convenience flag.
   module Builtins
     module_function
 
-    def register_core(klass)
-      register_help(klass)    unless klass.commands.key?('help')
+    # Single registration entry point - identical in every context
+    # (project Hammerfile or bare `hammer` binary). Namespacing under
+    # `h:` removes the old collision worries, so there's no core vs
+    # no-project split and no hidden-desc dance: the same tasks register
+    # everywhere, always dispatchable, and surface in the listing only
+    # under the extended `--help` view (the `@builtin_namespace` flag).
+    def register(klass)
       register_default(klass) unless klass.commands.key?('default')
-      register_update(klass)  unless klass.commands.key?('update')
-      register_agents(klass)  unless klass.commands.key?('agents')
-      register_version(klass) unless klass.commands.key?('version')
-    end
 
-    def register_no_project(klass)
-      register_recipes(klass) unless klass.commands.key?('recipes')
-      register_init(klass)    unless klass.commands.key?('init')
+      existed = klass.namespaces.key?('h')
+      klass.namespace(:h) {}          # ensure/reopen the reserved subclass
+      h = klass.namespaces['h']
+      # Flag the tree so the compact listing prunes it - the built-ins
+      # only show under the extended `--help` view (always dispatchable).
+      # Skip when the user already owns an `h:` namespace, so their own
+      # tasks stay visible in the bare listing.
+      h.instance_variable_set(:@builtin_namespace, true) unless existed
+      register_help(h)    unless h.commands.key?('help')
+      register_update(h)  unless h.commands.key?('update')
+      register_agents(h)  unless h.commands.key?('agents')
+      register_version(h) unless h.commands.key?('version')
+      register_recipes(h) unless h.commands.key?('recipes')
+      register_init(h)    unless h.commands.key?('init')
     end
 
     def register_help(klass)
@@ -37,9 +44,9 @@ class Hammer
             per-command help; with a namespace prefix prints that
             namespace's command listing.
           TXT
-          example 'help'
-          example 'help build'
-          example 'help db:'
+          example 'h:help'
+          example 'h:help build'
+          example 'h:help db:'
           proc do |opts|
             self.class.root.print_help(opts[:args].first, extended: true)
           end
@@ -109,7 +116,7 @@ class Hammer
     # invocation lists; opts pick the action and positional args carry
     # the recipe name (and optional target path for --install). Run via
     # `--run NAME [ARGS]` - use `--` to forward flags to the recipe
-    # itself (e.g. `hammer recipes --run srt -- --help`).
+    # itself (e.g. `hammer h:recipes --run srt -- --help`).
     def register_recipes(klass)
       klass.class_eval do
         task :recipes do
@@ -123,12 +130,12 @@ class Hammer
           opt :path,    type: :boolean, desc: 'print recipe abs path'
           opt :edit,    type: :boolean, desc: 'open recipe in $EDITOR (copies gem -> user dir first)'
           opt :run,     type: :boolean, desc: 'run a recipe without installing its bin (forwards remaining args)'
-          example 'recipes'
-          example 'recipes --install srt ~/bin/srt    # write + chmod in one shot'
-          example 'recipes --install srt > ~/bin/srt && chmod +x $_'
-          example 'recipes --show srt'
-          example 'recipes --run srt extract movie.mp4'
-          example 'recipes --run srt -- --help        # -- forwards flags to the recipe'
+          example 'h:recipes'
+          example 'h:recipes --install srt ~/bin/srt    # write + chmod in one shot'
+          example 'h:recipes --install srt > ~/bin/srt && chmod +x $_'
+          example 'h:recipes --show srt'
+          example 'h:recipes --run srt extract movie.mp4'
+          example 'h:recipes --run srt -- --help        # -- forwards flags to the recipe'
           proc do |opts|
             args = opts[:args]
             if opts[:install]
@@ -170,7 +177,7 @@ class Hammer
 
       def require_name!(name, action)
         return name if name
-        Shell.print_error "missing recipe name (usage: recipes --#{action} NAME)"
+        Shell.print_error "missing recipe name (usage: h:recipes --#{action} NAME)"
         exit 1
       end
 
@@ -192,7 +199,7 @@ class Hammer
           Shell.say "#{source}:", :yellow
           items.each_key do |name|
             _n, desc, installed = rows.find { |r| r.first == name }
-            status = installed ? "(installed: #{installed})" : "[install: hammer recipes --install #{name}]"
+            status = installed ? "(installed: #{installed})" : "[install: hammer h:recipes --install #{name}]"
             line = "  #{name.ljust(width)}  # #{desc}"
             Shell.say line
             Shell.say "  #{' ' * width}    #{status}", :gray
@@ -242,7 +249,7 @@ class Hammer
       end
 
       # For a gem recipe, offer to copy to user dir first so edits
-      # survive `hammer update`. Then exec $EDITOR on the file.
+      # survive `hammer h:update`. Then exec $EDITOR on the file.
       def edit(name)
         path = Hammer::Recipe.path(name) or fail_unknown(name)
         editor = ENV['EDITOR'] || ENV['VISUAL']

data/lib/hammer/dotenv.rb

@@ -38,8 +38,9 @@ class Hammer
         key = key.strip
         next if key.empty?
         val = val.strip
-        if (val.start_with?('"') && val.end_with?('"')) ||
-           (val.start_with?("'") && val.end_with?("'"))
+        if val.length >= 2 &&
+           ((val.start_with?('"') && val.end_with?('"')) ||
+            (val.start_with?("'") && val.end_with?("'")))
           val = val[1..-2]
         end
         out[key] = val

data/lib/hammer/loader.rb

@@ -38,31 +38,37 @@ class Hammer
 
     def resolve_pattern(anchor, pattern)
       abs = File.expand_path(pattern, anchor)
+      # A real file/dir wins over glob interpretation, so a literal path
+      # whose name contains [ ] { } * ? still resolves. Directory: discover
+      # *_hammer.rb under it (empty result is OK - an app may have none).
+      return [abs] if File.file?(abs)
+      return discover(abs) if File.directory?(abs)
       if abs.match?(/[\*\?\[\{]/)
         matches = Dir.glob(abs).sort
         raise Hammer::Error, "load: no files matched #{pattern.inspect}" if matches.empty?
         return matches
       end
-      # Directory: discover *_hammer.rb under it. Empty result is OK
-      # (an app may legitimately have no fragments).
-      return discover(abs) if File.directory?(abs)
-      return [abs] if File.file?(abs)
       raise Hammer::Error, "load: no files matched #{pattern.inspect}"
     end
 
     def discover(dir)
       return [] unless File.directory?(dir)
       out = []
-      walk(dir, out)
+      walk(dir, out, {})
       out.sort
     end
 
-    def walk(dir, out)
+    # `seen` tracks visited real paths so a cyclic directory symlink
+    # doesn't recurse forever.
+    def walk(dir, out, seen)
+      real = File.realpath(dir) rescue dir
+      return if seen[real]
+      seen[real] = true
       Dir.each_child(dir) do |entry|
         full = File.join(dir, entry)
         if File.directory?(full)
           next if SKIP_DIRS.include?(entry) || entry.start_with?('.')
-          walk(full, out)
+          walk(full, out, seen)
         elsif entry.end_with?('_hammer.rb')
           out << full
         end

data/lib/hammer/option.rb

@@ -59,6 +59,8 @@ class Hammer
       when :array   then value.is_a?(Array) ? value : value.to_s.split(',')
       else value.to_s
       end
+    rescue ArgumentError, TypeError
+      raise Hammer::Parser::Error, "invalid #{type} value for --#{name}: #{value.inspect}"
     end
 
     def usage

data/lib/hammer/parser.rb

@@ -8,9 +8,9 @@ class Hammer
       @options    = options
       @by_switch  = {}
       options.each do |opt|
-        @by_switch[opt.switch] = opt
-        @by_switch[opt.negation] = opt if opt.boolean?
-        opt.aliases.each { |a| @by_switch[a] = opt }
+        register_switch(opt.switch, opt)
+        register_switch(opt.negation, opt) if opt.boolean?
+        opt.aliases.each { |a| register_switch(a, opt) }
       end
     end
 
@@ -31,7 +31,11 @@ class Hammer
         if token.start_with?('--') && token.include?('=')
           key, val = token.split('=', 2)
           opt = lookup!(key)
-          values[opt.name] = opt.cast(val)
+          if opt.boolean? && key.start_with?('--no-')
+            values[opt.name] = !opt.cast(val)   # `--no-x=false` -> true
+          else
+            values[opt.name] = opt.cast(val)
+          end
           i += 1
           next
         end
@@ -50,7 +54,18 @@ class Hammer
           next
         end
 
-        if token.start_with?('-') && token.length > 1
+        # Glued short flag with value: `-pVALUE` (non-boolean short opts only).
+        if token.start_with?('-') && !token.start_with?('--') && token.length > 2
+          if (opt = @by_switch[token[0, 2]]) && !opt.boolean?
+            values[opt.name] = opt.cast(token[2..])
+            i += 1
+            next
+          end
+        end
+
+        # Dash-led and not a negative number -> a genuinely unknown flag.
+        # Bare `-` and negative numbers (`-5`) fall through to positionals.
+        if token.start_with?('-') && token.length > 1 && token !~ /\A-\d/
           raise Error, "unknown option: #{token}"
         end
 
@@ -59,15 +74,21 @@ class Hammer
       end
 
       # Fill un-set non-boolean opts from positional args in declaration
-      # order. Booleans always need an explicit flag.
+      # order. Booleans always need an explicit flag. Scalars take one
+      # positional each; an :array opt slurps whatever's left, so it's
+      # filled last and never starves a later-declared scalar opt.
+      array_opt = nil
       @options.each do |opt|
-        break if positional.empty?
         next if opt.boolean? || values.key?(opt.name)
         if opt.type == :array
-          values[opt.name] = opt.cast(positional.shift(positional.size))
-        else
-          values[opt.name] = opt.cast(positional.shift)
+          array_opt = opt
+          next
         end
+        break if positional.empty?
+        values[opt.name] = opt.cast(positional.shift)
+      end
+      if array_opt && !positional.empty?
+        values[array_opt.name] = array_opt.cast(positional.shift(positional.size))
       end
 
       @options.each do |opt|
@@ -80,6 +101,15 @@ class Hammer
 
     private
 
+    # Map a flag string to its option, refusing silent shadowing when two
+    # options would claim the same switch/negation/alias.
+    def register_switch(flag, opt)
+      if (prev = @by_switch[flag]) && prev != opt
+        raise Error, "flag #{flag} claimed by both :#{prev.name} and :#{opt.name}"
+      end
+      @by_switch[flag] = opt
+    end
+
     def lookup!(key)
       @by_switch[key] or raise Error, "unknown option: #{key}"
     end

data/lib/hammer/recipe.rb

@@ -49,14 +49,14 @@ class Hammer
       ''
     end
 
-    # Ruby wrapper text printed by `hammer recipes --install`. User
+    # Ruby wrapper text printed by `hammer h:recipes --install`. User
     # redirects it to a file in PATH and chmods +x. The leading comment
     # documents the canonical install command. Name is passed as a
     # string literal so hyphenated names (`git-helper`) work too.
     def stub(name)
       <<~RUBY
         #!/usr/bin/env ruby
-        # install: hammer recipes --install #{name} > ~/bin/#{name} && chmod +x $_
+        # install: hammer h:recipes --install #{name} > ~/bin/#{name} && chmod +x $_
         require 'lux-hammer'
         Hammer.recipe('#{name}', ARGV)
       RUBY

data/lib/hammer/shell.rb

@@ -13,8 +13,11 @@ class Hammer
     module_function
 
     def color?
-      return @color if defined?(@color)
-      @color = $stdout.tty? && ENV['NO_COLOR'].nil?
+      # Only an explicit color!(value) override is sticky; otherwise the
+      # tty decision is recomputed so a redirected $stdout (tests, capture
+      # blocks) is honored instead of frozen at first read.
+      return @color if defined?(@color) && !@color.nil?
+      $stdout.tty? && ENV['NO_COLOR'].nil?
     end
 
     def color!(value)