lux-hammer 0.2.9 → 0.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c947550570c131a847f744a29edc640efd04f969648bfc79926092f125a88559
-  data.tar.gz: 672a2a5fbf302fae7853ca72dc0fb7bca4e42a0723201c45fba57845b8c0b541
+  metadata.gz: f0f8f5abc50111342c80fbfc411408159e625d00e52a31dc8f8956ac658c21f0
+  data.tar.gz: d05eb3f51a19efa9d1a9328229a4dbb5b680eb91c1b36c9cb8f5e973cfc6f17d
 SHA512:
-  metadata.gz: 85e701c6c4ce14be709878d1ba055c5dc53d02f6d5ea41bdc1afe50f36444ce0964852c158ff315e7a085c3adebfcca7b336782b7feb6c7999f19d3e2f0aa52d
-  data.tar.gz: 20e83b75b2578870ceb1c06cb7f917601f524d236943eb906abc59340fe531c5f654897ff5d4b829f3cc176269f7dfe10791551e5bdff4a4726b0e1459fb90d7
+  metadata.gz: 5bf720911c5338c70a41f29af05ee2fad030ec54faad56727d9843bdae46355dbf22ef17e722c9196edf2aba7cdc9458f50dade6ca518f4d2709eeb2888ed43c
+  data.tar.gz: 005cc75962461f3e7c6e11ae04e31b99cec50b5cc1401b27ba968a28a64bf648599097d133fe8bd306896e99c5b76e020546b6cae4b867af85b015d19da5a2e3

data/.version

@@ -1 +1 @@
-0.2.9
+0.3.1

data/AGENTS.md

@@ -182,7 +182,10 @@ explicit ADR-level discussion. Keys:
   is the whole API. `Hammer.cli` warms the cache before chdir-ing into
   the Hammerfile's directory so the resolved name stays relative to the
   cwd the user invoked from.
-* `hammer` (no args), `hammer -h`, and `hammer --help` all print top-level help.
+* `hammer` (no args) prints just the command listing (with a top gray
+  `lux-hammer VERSION - <homepage>` banner for the hammer binary).
+* `hammer -h` / `hammer --help` adds global flags, a small Hammerfile
+  example, and the footer link on top of the same listing.
 * `hammer COMMAND -h` / `--help` prints per-command help (reserved on every command).
 * Commands listed flat with colon paths, grouped by top-level namespace.
 * Bare namespace (`hammer db`) prints the same listing scoped to that

data/lib/hammer/shell.rb

@@ -94,9 +94,13 @@ class Hammer
       return choose_numbered(items) unless $stdin.tty? && $stdin.respond_to?(:raw)
 
       selected = 0
+      # In raw mode \n is not translated to \r\n, so the picker uses \r\n
+      # explicitly. The initial draw happens in cooked mode but \r\n is
+      # harmless there.
       redraw = lambda do |highlight = :cyan|
         items.each_with_index do |item, i|
-          puts(i == selected ? paint("> #{item}", highlight) : "  #{item}")
+          line = i == selected ? paint("> #{item}", highlight) : "  #{item}"
+          $stdout.print "#{line}\r\n"
         end
       end
       redraw.call
@@ -109,11 +113,11 @@ class Hammer
             case ch
             when "\r", "\n"
               # Collapse the list to the chosen line, in green.
-              $stdout.print "\e[#{items.size}A\e[J"
-              puts paint("> #{items[selected]}", :green)
+              $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
-              $stdout.print "\e[#{items.size}A\e[J"
+              $stdout.print "\e[#{items.size}A\r\e[J"
               return nil
             when "\e"
               # ESC may stand alone or start an arrow sequence \e[A / \e[B.
@@ -123,13 +127,13 @@ class Hammer
                 when 'B' then selected = (selected + 1) % items.size
                 end
               else
-                $stdout.print "\e[#{items.size}A\e[J"
+                $stdout.print "\e[#{items.size}A\r\e[J"
                 return nil
               end
             when 'k' then selected = (selected - 1) % items.size
             when 'j' then selected = (selected + 1) % items.size
             end
-            $stdout.print "\e[#{items.size}A\e[J"
+            $stdout.print "\e[#{items.size}A\r\e[J"
             redraw.call
           end
         end

data/lib/lux-hammer.rb

@@ -325,20 +325,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,24 +556,29 @@ 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 full
         each_command { |path, c| print_full_block(path, c) unless c.desc.empty? }
@@ -589,11 +586,10 @@ class Hammer
         Shell.say ''
         print_command_list(self)
       end
-      print_global_flags
-      print_footer
+      print_extras if extended
     end
 
-    def print_namespace_help(prefix, ns, full: false)
+    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 +601,7 @@ 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
+      print_extras if extended
     end
 
     # One "task block" for the expanded listing: blank line separator
@@ -618,6 +613,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 +641,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 '  --ai  # Print AGENTS.md - AI-friendly Hammerfile authoring docs'
     end
 
     def print_footer
@@ -633,6 +649,35 @@ 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
+          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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: lux-hammer
 version: !ruby/object:Gem::Version
-  version: 0.2.9
+  version: 0.3.1
 platform: ruby
 authors:
 - Dino Reic