lux-hammer 0.3.5 → 0.3.7

data/lib/lux-hammer.rb

@@ -141,6 +141,7 @@ class Hammer
     # lives at `opts[:args]`.
     def task(name, &block)
       cmd = Command.new(name: name.to_s)
+      cmd.location = source_location_of(block)
       handler = CommandBuilder.new(cmd).instance_eval(&block)
       unless handler.is_a?(Proc)
         raise Error, <<~MSG
@@ -161,6 +162,12 @@ class Hammer
         MSG
       end
       cmd.handler = handler
+
+      if (prev = commands[cmd.name])
+        cmd.prev_location = prev.location
+        warn_redefinition('task', cmd.name, prev.location, cmd.location)
+      end
+
       commands[cmd.name] = cmd
 
       # `task` ignores pending class-level state, but clear it so a
@@ -181,12 +188,7 @@ class Hammer
     #     namespace :users do ... end
     #   end
     #
-    # `:self` is reserved for the `hammer` binary's built-ins (see
-    # Hammer::Builtins). User code that tries to open it raises.
     def namespace(name, &block)
-      if name.to_s == 'self' && !Thread.current[:hammer_builtins_loading]
-        raise Error, "namespace 'self' is reserved for hammer's built-in commands"
-      end
       sub = Class.new(Hammer)
       # Track the top-level CLI class so cross-invocation
       # (`hammer 'ns:cmd'`) from inside a namespaced command dispatches
@@ -199,7 +201,14 @@ class Hammer
       # "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
+
       @namespaces[name.to_s] = sub
     end
 
@@ -236,6 +245,21 @@ class Hammer
       @parent
     end
 
+    # "file:line" of the block that defined a task/namespace. Falls back
+    # to "(unknown)" for blocks without a usable source_location (rare -
+    # built-in C-defined procs, eval'd blocks).
+    def source_location_of(block)
+      loc = block&.source_location
+      loc ? "#{loc[0]}:#{loc[1]}" : '(unknown)'
+    end
+
+    # Emit a yellow [hammer] warning on stderr when a task/namespace is
+    # redefined. Last write wins (commands[name] = cmd), but the prior
+    # location is captured so listings can tag the entry as `(redefined)`.
+    def warn_redefinition(kind, name, prev_loc, new_loc)
+      warn Shell.paint("[hammer] redefined #{kind} :#{name} - was #{prev_loc || '(unknown)'}, now #{new_loc || '(unknown)'}", :yellow)
+    end
+
     # Root -> ... -> self. Used to gather `before` hooks for a command.
     def ancestor_chain
       chain = []
@@ -340,13 +364,18 @@ class Hammer
       argv = argv.dup
       name = argv.shift
 
-      if name.nil?
-        return print_help
+      # Bare invocation OR leading flag (other than -h/--help) -> :default
+      # task. Re-prepend the flag so :default's option parser sees it.
+      # If no :default is defined, fall back to top-level help.
+      if name.nil? || (name.start_with?('-') && name != '-h' && name != '--help')
+        argv.unshift(name) if name
+        return dispatch_to_builtin('default', argv) { print_help }
       end
 
+      # Explicit help requests -> :help task. Remaining positionals (e.g.
+      # `help build`, `help db:`) reach :help via opts[:args].
       if name == 'help' || name == '-h' || name == '--help'
-        target = argv.shift
-        return print_help(target, extended: true)
+        return dispatch_to_builtin('help', argv) { print_help(argv.first, extended: true) }
       end
 
       # Trailing colon ("db:") -> namespace listing. Bare ":" lists root.
@@ -375,6 +404,16 @@ class Hammer
       exit 1
     end
 
+    # Run a built-in routing task (:default or :help) if defined,
+    # otherwise yield to the fallback block. The implicit run banner
+    # is suppressed (the user typed `hammer --version`, not `hammer
+    # default --version` - no point echoing the rewritten form).
+    def dispatch_to_builtin(name, argv)
+      cmd = commands[name]
+      return yield unless cmd
+      run_command(cmd, argv, full: name, quiet: true)
+    end
+
     public
 
     # Find a command by canonical name or alt within this class. Falls
@@ -497,14 +536,14 @@ class Hammer
       end
     end
 
-    def run_command(cmd, argv, full: nil)
+    def run_command(cmd, argv, full: nil, quiet: false)
       # -h / --help is reserved on every command. Anywhere before a `--`
       # stop-marker, it short-circuits to per-command help.
       return print_command_help(cmd, full) if help_requested?(argv)
 
       positional, opts = Parser.new(cmd.options).parse(argv)
       opts[:args] = positional
-      print_run_banner(cmd, full || cmd.name, positional, opts)
+      print_run_banner(cmd, full || cmd.name, positional, opts) unless quiet || ENV['HAMMER_QUIET']
       instance = new
       run_before_hooks(instance, opts)
       run_needs(cmd)
@@ -623,7 +662,7 @@ class Hammer
       entries.each do |name, file|
         desc = Hammer::Recipe.desc(file)
         installed = Hammer::Recipe.installed_path(name)
-        suffix = installed ? "(installed: #{installed})" : "[install: #{program_name} self:recipe install #{name}]"
+        suffix = installed ? "(installed: #{installed})" : "[install: #{program_name} recipes --install #{name}]"
         Shell.say "  #{name.ljust(width)}  # #{desc}"
         Shell.say "  #{' ' * width}    #{suffix}", :gray
       end
@@ -632,8 +671,8 @@ 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 (self:, Recipes:, --update alias) is
-    # reserved for `hammer --help` at the top level.
+    # 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)
       Shell.say "Usage: #{program_name} #{prefix}:COMMAND [ARGS]", :cyan
       rows = []
@@ -678,14 +717,16 @@ class Hammer
       print_footer unless hammer_bin
     end
 
-    # Global flags only exist when invoked via the `hammer` binary
-    # (see `Hammer.cli`), not for user-built CLIs that call `start`
-    # on their own subclass.
+    # Listed under `Default task options:` in `--help` so users see what
+    # flags fire on bare-flag invocation (`hammer --version` etc).
+    # Re-rendered from the live `:default` task so user-defined
+    # overrides surface their own flags here automatically.
     def print_global_flags
-      return unless root.instance_variable_get(:@hammer_binary)
+      default = root.commands['default']
+      return unless default && !default.options.empty?
       Shell.say ''
-      Shell.say 'Global:', :yellow
-      Shell.say '  --update  # alias for `self:update`'
+      Shell.say 'Default task options:', :yellow
+      default.options.each { |o| Shell.say "  #{o.usage}" }
     end
 
     def print_footer
@@ -693,35 +734,13 @@ class Hammer
       Shell.say "powered by hammer - #{HOMEPAGE}", :gray
     end
 
-    # Small Hammerfile cheat-sheet shown under `hammer --help`. Touches
-    # the main surface area (task/desc/example/opt, namespace, before,
-    # needs, sh, say) without trying to be exhaustive - that's --ai's job.
+    # Hammerfile cheat-sheet shown under `hammer --help`. Same content
+    # as `hammer --init` writes - single source of truth via
+    # `Hammer::STARTER_HAMMERFILE`. For exhaustive docs see `hammer agents`.
     def print_hammerfile_example
       Shell.say ''
       Shell.say 'Hammerfile example:', :yellow
-      Shell.say <<~RUBY
-          desc 'My project tools - build, deploy, test'
-
-          task :hello do
-            desc    'Greet someone'
-            example 'hello world --loud'
-            opt :loud, type: :boolean, alias: :l
-            proc do |opts|
-              msg = "hello \#{opts[:args].first || 'world'}"
-              say(opts[:loud] ? msg.upcase : msg, :cyan)
-            end
-          end
-
-          namespace :db do
-            before { hammer :env }
-
-            task :migrate do
-              desc  'Run migrations'
-              needs 'db:check'
-              proc  { sh 'bin/rails db:migrate' }
-            end
-          end
-      RUBY
+      Shell.say Hammer::STARTER_HAMMERFILE
     end
 
     def print_command_list(klass, prefix = nil)
@@ -755,6 +774,7 @@ class Hammer
     def emit_rows(rows, width)
       rows.each do |full, c|
         brief = c.alts.empty? ? c.brief : "#{c.brief} (alt: #{c.alts.join(', ')})"
+        brief = "#{brief} #{Shell.paint('(redefined)', :yellow)}" if c.prev_location
         Shell.say "  #{program_name} #{full.ljust(width)}  # #{brief}"
       end
     end
@@ -866,7 +886,7 @@ class Hammer
       Shell.print_error "unknown recipe: #{name}"
       Shell.say 'available recipes:', :yellow
       Recipe.all.keys.sort.each { |n| Shell.say "  #{n}" }
-      Shell.say 'try `hammer self:recipe` to list with descriptions', :gray
+      Shell.say 'try `hammer recipes` to list with descriptions', :gray
       exit 1
     end
 
@@ -889,12 +909,45 @@ class Hammer
     end
   end
 
-  # Default install dir used by install.sh and `hammer --update`.
+  # Canonical starter Hammerfile. Written verbatim by `hammer --init`
+  # and shown inline by `print_hammerfile_example` (the `Hammerfile
+  # example:` block in `hammer --help`) - one source of truth for both.
+  # Annotated as a mini tutorial of the common DSL surface in one task.
+  # Single-quoted heredoc so file contents pass through unescaped.
+  STARTER_HAMMERFILE ||= <<~'RUBY'
+    desc 'My project tools'
+
+    # `namespace :name do ... end` groups tasks under a colon prefix.
+    # Address as `hammer demo:greet`.
+    namespace :demo do
+      # run before every task - global, or on a namespace
+      before { say.gray "[demo] booting in #{Dir.pwd}" }
+
+      task :greet do
+        desc    'Demo task - shows the common DSL features in one place'
+        example 'demo:greet world --from=alice --loud --times=3'
+        alt     :hi                     # `hammer demo:hi` also dispatches here
+
+        opt :from,  default: 'anon',              desc: 'who is greeting'
+        opt :loud,  type: :boolean, alias: :l,    desc: 'shout the greeting'
+        opt :times, type: :integer, default: 1,   desc: 'repeat N times'
+
+        proc do |opts|
+          who = opts[:args].first || 'world'
+          msg = "hello #{who} from #{opts[:from]}"
+          msg = msg.upcase if opts[:loud]
+          opts[:times].times { say msg, :cyan }
+        end
+      end
+    end
+  RUBY
+
+  # Default install dir used by install.sh and `hammer update`.
   SELF_UPDATE_DIR  ||= File.expand_path('~/.local/share/lux-hammer')
   SELF_UPDATE_REPO ||= 'https://github.com/dux/hammer.git'
   SELF_INSTALL_URL ||= 'https://raw.githubusercontent.com/dux/hammer/main/install.sh'
 
-  # `hammer --update`: pull main in the install-script checkout and
+  # `hammer update`: pull main in the install-script checkout and
   # reinstall the gem. Assumes the install.sh layout - if the dir is
   # missing, point the user at the curl-pipe installer.
   def self.self_update
@@ -929,31 +982,25 @@ class Hammer
   # finds a Hammerfile, evaluates it as the block DSL, then dispatches
   # ARGV against the resulting CLI.
   #
-  # The `self:` namespace (recipe management, AGENTS.md dump, self-
-  # update) is registered on-demand when the user invokes help or
-  # types a `self:` path - see `builtins_triggered?`.
+  # `--system` forces the no-Hammerfile branch even from inside a
+  # project - the escape hatch for reaching `recipes`/`init` when a
+  # user-defined task tree would otherwise own the root.
   def self.cli(argv = ARGV)
-    # `--update` is a back-compat alias for `self:update`. Rewrite so
-    # normal dispatch handles it (after builtins registration).
-    if (i = argv.index('--update'))
-      argv = argv.dup
-      argv.delete_at(i)
-      argv.unshift('self:update')
-    end
-
-    wants_builtins = builtins_triggered?(argv)
+    argv = argv.dup
+    force_system = !!argv.delete('--system')
 
-    path = find_hammerfile(Dir.pwd)
+    path = force_system ? nil : find_hammerfile(Dir.pwd)
     unless path
-      # No Hammerfile - still allow `hammer self:*` commands to run
-      # (they don't depend on a project). Otherwise print the help-ish
-      # "create one" message.
-      if wants_builtins
+      # No Hammerfile (or --system) - all built-ins are reachable. Bare
+      # `hammer`, `hammer recipes`, `hammer update`, `hammer agents`,
+      # `hammer version`, `hammer init` all work.
+      if force_system || dispatches_to_builtin?(argv) || looks_like_builtin?(argv)
         klass = Class.new(Hammer)
         klass.instance_variable_set(:@hammer_binary, true)
         klass.program_name
         require_relative 'hammer/builtins'
-        Hammer::Builtins.register(klass)
+        Hammer::Builtins.register_core(klass)
+        Hammer::Builtins.register_no_project(klass)
         klass.start(argv)
         return
       end
@@ -974,24 +1021,17 @@ class Hammer
 
       Shell.say "create one - example:"
       puts
-      Shell.say <<~RUBY
-        desc 'My project tools'
-
-        task :hello do
-          desc 'say hello'
-          proc do |opts|
-            say.green "hello \#{opts[:args].first || 'world'}"
-          end
-        end
-      RUBY
+      Shell.say STARTER_HAMMERFILE
       Shell.say ''
-      Shell.say "tip: run `#{File.basename($PROGRAM_NAME)} self:ai` for AI-friendly Hammerfile authoring docs", :gray
+      bin = File.basename($PROGRAM_NAME)
+      Shell.say "tip: run `#{bin} init` to drop the example above into ./Hammerfile", :gray
+      Shell.say "tip: run `#{bin} agents` for AI-friendly Hammerfile authoring docs", :gray
       exit 1
     end
 
     klass = Class.new(Hammer)
     # Mark this class as the `hammer` binary's root so help output can
-    # surface binary-only sections (`Recipes:`, `self:` namespace).
+    # surface binary-only sections (`Recipes:` listing).
     klass.instance_variable_set(:@hammer_binary, true)
     # Resolve before chdir so paths like `bin/foo` stay relative to the
     # cwd the user actually invoked from. `program_name` memoizes.
@@ -1006,24 +1046,37 @@ class Hammer
     # are NOT visible during Hammerfile evaluation, only inside handlers.
     Hammer::Dotenv.load(Dir.pwd) if klass.dotenv_enabled?
 
-    if wants_builtins
-      require_relative 'hammer/builtins'
-      Hammer::Builtins.register(klass)
-    end
+    # Core built-ins register AFTER Hammerfile eval so user-defined
+    # tasks win (the `unless commands.key?(...)` guards in register_core
+    # skip the built-in when overridden - no redefinition warning).
+    # `register_no_project` (:recipes, :init) is intentionally NOT
+    # called here - those would clash too easily with user tasks. Use
+    # `hammer --system recipes` to reach them from inside a project.
+    require_relative 'hammer/builtins'
+    Hammer::Builtins.register_core(klass)
 
     klass.start(argv)
   end
 
-  # True if argv references the `self:` namespace or asks for help -
-  # any of which means the user wants to see / invoke the built-ins.
-  # Bare `hammer` (empty argv) does NOT trigger - the no-args listing
-  # stays a clean project-command view without `self:` or `Recipes:`.
-  # Cheap scan, runs once per invocation.
-  def self.builtins_triggered?(argv)
-    argv.any? do |a|
-      a == '--help' || a == '-h' || a == 'help' ||
-        a == 'self' || a.start_with?('self:')
-    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
+  # Hammerfile to run.
+  def self.dispatches_to_builtin?(argv)
+    return true if argv.empty?
+    first = argv.first
+    first == 'help' || first == '-h' || first == '--help' || first.start_with?('-')
+  end
+
+  # True if argv names a built-in task (`recipes`, `update`, `agents`,
+  # `version`, `init`). Used in the no-Hammerfile branch to wake up the
+  # built-ins for invocations like `hammer recipes` that aren't a flag
+  # or help request.
+  BUILTIN_TASKS ||= %w[recipes update agents version init].freeze
+  def self.looks_like_builtin?(argv)
+    first = argv.first
+    return false unless first
+    BUILTIN_TASKS.include?(first) || BUILTIN_TASKS.any? { |t| first.start_with?("#{t}:") }
   end
 
   # Walk up the directory tree looking for a Hammerfile.