lux-hammer 0.2.9 → 0.3.3

data/lib/lux-hammer.rb

@@ -6,6 +6,7 @@ require_relative 'hammer/loader'
 require_relative 'hammer/builder'
 require_relative 'hammer/command_builder'
 require_relative 'hammer/dotenv'
+require_relative 'hammer/recipe'
 
 # Thor-inspired tiny CLI builder.
 #
@@ -55,6 +56,7 @@ class Hammer
       sub.instance_variable_set(:@before_hooks, [])
       sub.instance_variable_set(:@parent, nil)
       sub.instance_variable_set(:@program_name, nil)
+      sub.instance_variable_set(:@app_desc, nil)
       sub.instance_variable_set(:@pending_desc, nil)
       sub.instance_variable_set(:@pending_examples, [])
       sub.instance_variable_set(:@pending_options, [])
@@ -110,6 +112,14 @@ class Hammer
       @program_name ||= default_program_name
     end
 
+    # Top-level description for the whole CLI. Set from a Hammerfile (block
+    # DSL) via `desc 'text'` at top level - see `Hammer::Builder#desc`.
+    # Rendered under the Usage line in `--help` output.
+    def app_desc(text = nil)
+      return @app_desc if text.nil?
+      @app_desc = text.to_s.rstrip
+    end
+
     # Program name shown in help/usage: the invocation path relative to cwd
     # if the script lives inside it (e.g. `bin/foo` when invoked from the
     # project root), otherwise the basename (e.g. `lux` for a globally
@@ -170,7 +180,13 @@ class Hammer
     #     task :migrate do ... end
     #     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
@@ -325,20 +341,12 @@ class Hammer
       name = argv.shift
 
       if name.nil?
-        # Bare invocation of the `hammer` binary: print a gem banner
-        # above the help so users can see which lux-hammer they have.
-        # Skipped for `-h` / `help` (those stay terse) and for user-
-        # built CLIs (their own program name, not lux-hammer).
-        if root.instance_variable_get(:@hammer_binary)
-          Shell.say "lux-hammer #{VERSION}"
-          Shell.say ''
-        end
         return print_help
       end
 
       if name == 'help' || name == '-h' || name == '--help'
         target = argv.shift
-        return print_help(target)
+        return print_help(target, extended: true)
       end
 
       # Trailing colon ("db:") -> namespace listing. Bare ":" lists root.
@@ -564,36 +572,69 @@ class Hammer
       scan.include?('-h') || scan.include?('--help')
     end
 
-    def print_help(target = nil, full: false)
+    # `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)
       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) if ns
+          return print_namespace_help(canonical, ns, extended: extended) 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) if ns
+        return print_namespace_help(canonical, ns, full: full, extended: extended) if ns
         Shell.print_error("unknown: #{target}")
         return
       end
 
+      print_top_banner
       Shell.say "Usage: #{program_name} COMMAND [ARGS]", :cyan
+      if @app_desc && !@app_desc.empty?
+        Shell.say ''
+        @app_desc.each_line { |l| Shell.say "  #{l.chomp}" }
+      end
       if full
         each_command { |path, c| print_full_block(path, c) unless c.desc.empty? }
       else
         Shell.say ''
         print_command_list(self)
       end
-      print_global_flags
-      print_footer
+      print_recipes_section if extended && root.instance_variable_get(:@hammer_binary)
+      print_extras if extended
     end
 
-    def print_namespace_help(prefix, ns, full: false)
+    # Lists recipes (gem + user-dir) under their own section in
+    # `hammer --help`. Each row shows the recipe's `# desc:` line and
+    # either an install hint or the path of the existing stub on PATH.
+    # Only rendered when this CLI is the `hammer` binary's root.
+    def print_recipes_section
+      entries = Hammer::Recipe.all
+      return if entries.empty?
+      Shell.say ''
+      Shell.say 'Recipes:', :yellow
+      width = entries.keys.map(&:length).max
+      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}]"
+        Shell.say "  #{name.ljust(width)}  # #{desc}"
+        Shell.say "  #{' ' * width}    #{suffix}", :gray
+      end
+    end
+
+    # `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.
+    def print_namespace_help(prefix, ns, full: false, extended: false)
       Shell.say "Usage: #{program_name} #{prefix}:COMMAND [ARGS]", :cyan
       rows = []
       sibling = find_namespace_sibling(prefix)
@@ -605,8 +646,6 @@ class Hammer
         width = rows.map { |path, _| path.length }.max
         emit_rows(rows.sort_by { |path, _| [path.count(':'), path] }, width)
       end
-      print_global_flags
-      print_footer
     end
 
     # One "task block" for the expanded listing: blank line separator
@@ -618,6 +657,27 @@ class Hammer
 
     HOMEPAGE ||= 'https://github.com/dux/hammer'.freeze
 
+    # Gray "lux-hammer X.Y.Z - <homepage>" line shown above top-level help
+    # in both bare-invocation and `--help` modes, so the link is always
+    # one glance away. User CLIs skip it (the lux-hammer name/link is
+    # irrelevant outside the `hammer` binary).
+    def print_top_banner
+      return unless root.instance_variable_get(:@hammer_binary)
+      Shell.say "lux-hammer #{VERSION} - #{HOMEPAGE}", :gray
+      Shell.say ''
+    end
+
+    # Extras shown only in the extended (`help` / `-h` / `--help`) view:
+    # global flags, GitHub footer, and a Hammerfile example for the
+    # `hammer` binary. The footer is skipped for the hammer binary
+    # because `print_top_banner` already surfaces the same link.
+    def print_extras
+      hammer_bin = root.instance_variable_get(:@hammer_binary)
+      print_global_flags
+      print_hammerfile_example if hammer_bin
+      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.
@@ -625,7 +685,7 @@ class Hammer
       return unless root.instance_variable_get(:@hammer_binary)
       Shell.say ''
       Shell.say 'Global:', :yellow
-      Shell.say '  --ai  # Print AGENTS.md (AI-friendly Hammerfile authoring docs)'
+      Shell.say '  --update  # alias for `self:update`'
     end
 
     def print_footer
@@ -633,6 +693,37 @@ 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.
+    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
+    end
+
     def print_command_list(klass, prefix = nil)
       rows = []
       # Commands without a `desc` are hidden from listings but still
@@ -758,6 +849,33 @@ class Hammer
     klass.start(argv)
   end
 
+  # Entry point for recipe stubs in PATH. A recipe is a standalone
+  # Hammerfile-style script bundled with the gem (or in
+  # ~/.config/hammer/recipes/) that is exposed as its own bin via a
+  # tiny Ruby wrapper containing:
+  #
+  #   require 'lux-hammer'
+  #   Hammer.recipe(:srt, ARGV)
+  #
+  # The recipe runs as a self-contained CLI: program_name is the recipe
+  # name, only its own tasks show in --help, no global hammer commands
+  # appear. Runs in the caller's cwd (no chdir, no Hammerfile lookup).
+  def self.recipe(name, argv = ARGV)
+    path = Recipe.path(name)
+    unless path
+      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
+      exit 1
+    end
+
+    klass = Class.new(Hammer)
+    klass.instance_variable_set(:@program_name, name.to_s)
+    Builder.new(klass).evaluate(File.read(path), path)
+    klass.start(argv)
+  end
+
   # Dump the gem's AGENTS.md to stdout - AI-optimized guide for
   # writing Hammerfiles. Bundled with the gem and resolved relative
   # to this file so it works from any install location.
@@ -771,20 +889,75 @@ class Hammer
     end
   end
 
+  # 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
+  # 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
+    dir = ENV['LUX_HAMMER_DIR'] || SELF_UPDATE_DIR
+    unless File.directory?(File.join(dir, '.git'))
+      Shell.print_error "no lux-hammer git checkout at #{dir}"
+      Shell.say 'reinstall with:', :yellow
+      Shell.say "  curl -fsSL #{SELF_INSTALL_URL} | bash"
+      exit 1
+    end
+
+    Shell.say "* updating lux-hammer at #{dir}", :cyan
+    Dir.chdir(dir) do
+      run_or_exit('git', 'fetch', '--quiet', 'origin', 'main')
+      run_or_exit('git', 'reset', '--quiet', '--hard', 'origin/main')
+      version = File.read('.version').strip
+      gem_file = "lux-hammer-#{version}.gem"
+      run_or_exit('gem', 'build', 'lux-hammer.gemspec', out: File::NULL)
+      run_or_exit('gem', 'install', '--quiet', gem_file)
+      File.unlink(gem_file) if File.exist?(gem_file)
+      Shell.say "* lux-hammer #{version} installed", :green
+    end
+  end
+
+  def self.run_or_exit(*cmd, **opts)
+    return if system(*cmd, **opts)
+    Shell.print_error "command failed: #{cmd.join(' ')}"
+    exit 1
+  end
+
   # Entry point for the `hammer` binary. Walks up from CWD until it
   # finds a Hammerfile, evaluates it as the block DSL, then dispatches
   # ARGV against the resulting CLI.
   #
-  # `--ai` is a meta-flag handled here, before Hammerfile lookup,
-  # so it works anywhere (no project required).
+  # 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?`.
   def self.cli(argv = ARGV)
-    if argv.include?('--ai')
-      print_ai_help
-      exit 0
+    # `--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)
+
     path = 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
+        klass = Class.new(Hammer)
+        klass.instance_variable_set(:@hammer_binary, true)
+        klass.program_name
+        require_relative 'hammer/builtins'
+        Hammer::Builtins.register(klass)
+        klass.start(argv)
+        return
+      end
+
       Shell.print_error "no Hammerfile found in #{Dir.pwd} or any parent directory"
 
       # Heuristic: *.rb files referencing `Hammer.` are likely inline CLIs
@@ -802,6 +975,8 @@ class Hammer
       Shell.say "create one - example:"
       puts
       Shell.say <<~RUBY
+        desc 'My project tools'
+
         task :hello do
           desc 'say hello'
           proc do |opts|
@@ -810,13 +985,13 @@ class Hammer
         end
       RUBY
       Shell.say ''
-      Shell.say "tip: run `#{File.basename($PROGRAM_NAME)} --ai` for AI-friendly Hammerfile authoring docs", :gray
+      Shell.say "tip: run `#{File.basename($PROGRAM_NAME)} self:ai` 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 globals like `--ai`.
+    # surface binary-only sections (`Recipes:`, `self:` namespace).
     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.
@@ -830,9 +1005,27 @@ class Hammer
     # `dotenv false` in the Hammerfile can suppress it. Trade-off: vars
     # 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
+
     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
+  end
+
   # Walk up the directory tree looking for a Hammerfile.
   def self.find_hammerfile(start)
     dir = File.expand_path(start)