lux-hammer 0.3.1 → 0.3.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f0f8f5abc50111342c80fbfc411408159e625d00e52a31dc8f8956ac658c21f0
-  data.tar.gz: d05eb3f51a19efa9d1a9328229a4dbb5b680eb91c1b36c9cb8f5e973cfc6f17d
+  metadata.gz: 8b7ace2215fd4ef5e5edf6ee82a418c4ff56770f2d15bdc6f6127f5bd155bba8
+  data.tar.gz: 2a6734f905d7d30f1cb1536a6a6004ceb60fde702a7a87ec2ce7f7a7efb75992
 SHA512:
-  metadata.gz: 5bf720911c5338c70a41f29af05ee2fad030ec54faad56727d9843bdae46355dbf22ef17e722c9196edf2aba7cdc9458f50dade6ca518f4d2709eeb2888ed43c
-  data.tar.gz: 005cc75962461f3e7c6e11ae04e31b99cec50b5cc1401b27ba968a28a64bf648599097d133fe8bd306896e99c5b76e020546b6cae4b867af85b015d19da5a2e3
+  metadata.gz: e211c85aa36eda42822fa8c2181bea5e4128a10de60e7d22574eb3f6f721c2dc556ceb432cd5bcb2c0e2644a30a0ed8f2d4ae5ff3503cdaf618f70a3917f5329
+  data.tar.gz: 54fdb3f2dbe42ab5cc4312c4a969d3a43fe0fb420336c32702efcca2a2790ad7df8cf90d2eea5949ee6cb2ce7a77e33217b784144ef7baceb9abf1a2ead125ce

data/.version

@@ -1 +1 @@
-0.3.1
+0.3.3

data/AGENTS.md

@@ -44,6 +44,9 @@ lib/hammer/command.rb       # One registered command (name, opts, alts, handler)
 lib/hammer/loader.rb        # `*_hammer.rb` fragment loader (auto/glob/file)
 lib/hammer/builder.rb       # Block-DSL context (Hammerfile / Hammer.run)
 lib/hammer/command_builder.rb # `task :name do ... end` context
+lib/hammer/recipe.rb        # Recipe discovery (gem + user dir, desc, stub)
+lib/hammer/builtins.rb      # Lazy-loaded `self:` namespace (recipe, ai, update)
+recipes/                    # Bundled recipes (each `<name>.rb` -> a bin via stub)
 test/dsl_test.rb            # DSL surface, dispatch, help formatting
 test/load_test.rb           # `load` / `*_hammer.rb` fragment loader
 test/parser_test.rb         # ARGV parsing edge cases
@@ -80,10 +83,25 @@ At class scope (for `def`-style commands):
 * Methods with arity 0 are called without opts; methods that take an arg
   receive the opts hash
 
+At Hammerfile (block-DSL) top-level scope only:
+
+* `desc 'CLI description'` - top-level summary shown under the `Usage:`
+  line in `hammer --help`. Multi-line allowed (via heredoc). This is
+  distinct from the class-DSL `desc` (which sets per-task pending
+  state for the next `def`).
+* `helpers do ... end` - shorthand for `class_eval` on the underlying
+  Hammer subclass. Use it to define private instance methods that task
+  procs can call as bare names (procs are `instance_exec`'d on the
+  subclass instance, so anything defined here is in scope). Helpers
+  can also call `say` / `choose` / `error` / `yes?` directly since
+  Hammer mixes in `Shell`.
+
 At class or `Hammerfile` scope:
 
 * `task :name do ... end`
-* `namespace :name do ... end`
+* `namespace :name do ... end` - `:self` is reserved for the `hammer`
+  binary's built-in namespace (see `lib/hammer/builtins.rb`). Defining
+  it from user code raises.
 * `dotenv false` - opt out of auto `.env` / `.env.local` loading.
   Only meaningful from the `hammer` binary (`Hammer.cli`); the load
   happens after Hammerfile evaluation, before dispatch. Shell-set vars
@@ -125,9 +143,15 @@ Runtime cross-invocation:
   (`bin/hammer`).
 * `Hammer.cli(argv = ARGV)` - internal entry for `bin/hammer` only:
   walks up from `Dir.pwd` for a `Hammerfile`, chdirs into its dir,
-  errors if none found anywhere up the tree. Not part of the
-  user-facing surface - don't recommend it in examples; `Hammer.run`
-  is what library users should reach for.
+  errors if none found anywhere up the tree. Also lazy-registers the
+  `self:` namespace when argv shows the user wants help or a
+  `self:`-prefixed command. 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,
+  no chdir, no dotenv auto-load. See `lib/hammer/recipe.rb`.
 * `class MyCli < Hammer; ... end; MyCli.start(ARGV)` - classic class
   DSL. `.start` is the dispatch primitive everything else funnels into.
 

data/README.md

@@ -63,11 +63,26 @@ gem install lux-hammer
 
 This installs the `hammer` binary and exposes `require 'lux-hammer'`.
 
+### Install from GitHub (latest main)
+
+```sh
+curl -fsSL https://raw.githubusercontent.com/dux/hammer/main/install.sh | bash
+```
+
+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
+```
+
 ## Quick start
 
 Create a `Hammerfile` in your project root:
 
 ```ruby
+desc 'My project tools - build, deploy, test'
+
 task :hello do
   desc 'say hi'
   proc do |opts|
@@ -86,6 +101,8 @@ hello dino
 $ hammer
 Usage: hammer COMMAND [ARGS]
 
+  My project tools - build, deploy, test
+
 Commands:
   hammer hello  # say hi
 ```
@@ -93,6 +110,10 @@ Commands:
 That's it. `hammer` walks up from your current directory looking for a
 `Hammerfile`, evaluates it, and dispatches.
 
+The top-level `desc 'text'` is optional - one line (or multi-line via
+a heredoc) describing what the CLI is for. It renders right under the
+`Usage:` line in `hammer --help`.
+
 ## Why hammer (the short pitch)
 
 A handful of papercuts from Rake and Thor that hammer just doesn't have.
@@ -462,6 +483,10 @@ hammer :                  # trailing colon at root: full help for every command
 Namespaces nest to any depth. There is no per-level dispatch - the root
 parses the whole colon path and walks the namespace tree.
 
+The `self:` namespace is reserved for hammer's own built-in commands
+(see [Recipes](#recipes-shareable-mini-clis-shipped-with-hammer)
+below). Defining `namespace :self` in a Hammerfile raises an error.
+
 ## Pre-hooks (`before`)
 
 A `before do ... end` block at the root scope or inside a `namespace`
@@ -971,6 +996,78 @@ Options:
   --admin
 ```
 
+## Recipes (shareable mini-CLIs shipped with hammer)
+
+A **recipe** is a standalone Hammerfile-style script bundled inside the
+`lux-hammer` gem under `recipes/`. Each recipe is exposed as its own
+top-level binary in your `PATH` - so `srt` becomes a real command, not
+`hammer srt:shift`.
+
+Listing what's available:
+
+```sh
+$ hammer self:recipe
+gem:
+  srt  # Subtitle (.srt) toolkit - shift timestamps, show stats
+         [install: hammer self:recipe install srt]
+```
+
+Installing one (you control the path; nothing is written for you):
+
+```sh
+$ hammer self:recipe install srt > ~/bin/srt && chmod +x ~/bin/srt
+$ srt --help
+Usage: srt COMMAND [ARGS]
+
+  Tiny .srt subtitle helper.
+
+Commands:
+  srt info   # Print cue count and total duration
+  srt shift  # Shift every timestamp by N seconds
+```
+
+The stub is a 3-line Ruby wrapper that re-enters lux-hammer at runtime,
+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 self:recipe`. The file
+body uses the same DSL as a Hammerfile - `task`, `namespace`, `before`,
+`load`. Example `~/.config/hammer/recipes/json.rb`:
+
+```ruby
+# desc: tiny JSON pretty-printer / minifier
+
+task :pretty do
+  desc 'Pretty-print JSON from stdin or a file'
+  proc do |opts|
+    require 'json'
+    src = opts[:args].first ? File.read(opts[:args].first) : $stdin.read
+    puts JSON.pretty_generate(JSON.parse(src))
+  end
+end
+```
+
+Install it the same way:
+
+```sh
+$ hammer self:recipe install json > ~/bin/json && chmod +x ~/bin/json
+```
+
+User-dir recipes override gem recipes with the same name, so you can
+fork without forking.
+
+### Other `self:recipe` actions
+
+```sh
+hammer self:recipe              # list all
+hammer self:recipe install      # interactive picker, then prints stub
+hammer self:recipe show <NAME>  # cat the recipe source
+hammer self:recipe path <NAME>  # absolute path
+hammer self:recipe edit <NAME>  # open in $EDITOR (copies gem -> user dir first)
+```
+
 ## Programmatic use
 
 Outside a Hammerfile, you can build a `Hammer` subclass and run it

data/lib/hammer/builder.rb

@@ -7,6 +7,30 @@ class Hammer
       @klass = klass
     end
 
+    # Top-level CLI description, shown under the Usage line in
+    # `hammer --help`. Multi-line strings render with each line indented.
+    def desc(text)
+      @klass.app_desc(text)
+    end
+
+    # Open the underlying Hammer subclass to add private instance methods
+    # callable from inside task procs. Lets recipe / Hammerfile authors
+    # share helpers without a `Foo.method` prefix or a separate module:
+    #
+    #   helpers do
+    #     def run(cmd) ; say cmd, :gray ; system cmd ; end
+    #   end
+    #
+    #   task :ship do
+    #     proc { run 'git push' }
+    #   end
+    #
+    # Procs run via `instance.instance_exec(opts, &handler)` on a fresh
+    # subclass instance, so anything `class_eval`'d here is in scope.
+    def helpers(&block)
+      @klass.class_eval(&block)
+    end
+
     def task(name, &block)
       @klass.task(name, &block)
     end
@@ -59,6 +83,26 @@ class Hammer
         target.send(m, *args, &block)
       end
     end
+
+    # Top-level `desc 'text'` from inside a Hammerfile / fragment - sets
+    # the CLI's overall description on the current target. Separate from
+    # the class-level `desc` (which is per-task pending state).
+    def desc(text)
+      target = Thread.current[:hammer_target]
+      raise Hammer::Error, '`desc` called outside a Hammer context ' \
+                           '(Hammerfile / Hammer.run block / *_hammer.rb)' unless target
+      target.app_desc(text)
+    end
+
+    # Same as Builder#helpers - top-level `helpers do ... end` in a
+    # fragment or Hammerfile adds private instance methods to the
+    # current target's class.
+    def helpers(&block)
+      target = Thread.current[:hammer_target]
+      raise Hammer::Error, '`helpers` called outside a Hammer context ' \
+                           '(Hammerfile / Hammer.run block / *_hammer.rb)' unless target
+      target.class_eval(&block)
+    end
   end
 end
 

data/lib/hammer/builtins.rb

@@ -0,0 +1,181 @@
+class Hammer
+  # Lazy-loaded "built-ins" attached under the reserved `self:` namespace
+  # of the `hammer` binary. Hosts management commands (recipes, AGENTS.md
+  # dump, self-update) that should not appear on every user-command run.
+  # `Hammer.cli` only calls `register` when argv shows the user is
+  # asking for help or invoking a `self:`-prefixed command.
+  module Builtins
+    module_function
+
+    # Wire the `self:` namespace into `klass`. Idempotent - safe to call
+    # twice; the second call replaces the existing subclass.
+    def register(klass)
+      Thread.current[:hammer_builtins_loading] = true
+      klass.namespace(:self) do
+        task :ai do
+          desc 'Print AGENTS.md (AI-friendly Hammerfile authoring docs)'
+          proc { Hammer.print_ai_help }
+        end
+
+        task :update do
+          desc 'Update lux-hammer from github main (requires install.sh checkout)'
+          proc { Hammer.self_update }
+        end
+
+        task :recipe do
+          desc <<~TXT
+            Manage recipes. First positional argument is the action.
+
+              (no args)              list all recipes
+              install [NAME] [PATH]  install stub. No PATH: print to stdout. With PATH: write + chmod +x.
+              show    NAME           cat recipe source
+              path    NAME           print recipe abs path
+              edit    NAME           open recipe in $EDITOR
+              run     NAME [ARGS]    run a recipe without installing its bin
+          TXT
+          example 'self:recipe'
+          example 'self:recipe install srt ~/bin/srt        # write + chmod in one shot'
+          example 'self:recipe install srt > ~/bin/srt && chmod +x $_'
+          example 'self:recipe show srt'
+          example 'self:recipe run srt extract movie.mp4'
+          example 'self:recipe run srt -- --help            # -- forwards flags to the recipe'
+          proc do |opts|
+            action, name, *rest = opts[:args]
+            Hammer::Builtins::Recipes.dispatch(action, name, rest)
+          end
+        end
+      end
+    ensure
+      Thread.current[:hammer_builtins_loading] = nil
+    end
+
+    # Implementations of the `self:recipe <action>` sub-commands, plus
+    # the no-action listing view. Kept in its own module so the
+    # namespace definition above stays small and skimmable.
+    module Recipes
+      module_function
+
+      def dispatch(action, name, rest = [])
+        case action
+        when nil       then list
+        when 'install' then install(name, rest.first)
+        when 'show'    then show(require_name!(name, 'show'))
+        when 'path'    then path(require_name!(name, 'path'))
+        when 'edit'    then edit(require_name!(name, 'edit'))
+        when 'run'     then Hammer.recipe(require_name!(name, 'run'), rest)
+        else
+          Shell.print_error "unknown action: #{action}"
+          Shell.say 'valid: install, show, path, edit, run (or omit for list)', :yellow
+          exit 1
+        end
+      end
+
+      def require_name!(name, action)
+        return name if name
+        Shell.print_error "missing recipe name (usage: self:recipe #{action} NAME)"
+        exit 1
+      end
+
+      # Group by source dir; each row shows desc and installed-or-not.
+      def list
+        groups = Hammer::Recipe.grouped
+        if groups.empty?
+          Shell.say 'no recipes found', :gray
+          return
+        end
+
+        rows = Hammer::Recipe.all.map do |name, path|
+          [name, Hammer::Recipe.desc(path), Hammer::Recipe.installed_path(name)]
+        end
+        width = rows.map { |n, _, _| n.length }.max
+
+        groups.each_with_index do |(source, items), i|
+          Shell.say '' if i > 0
+          Shell.say "#{source}:", :yellow
+          items.each_key do |name|
+            _n, desc, installed = rows.find { |r| r.first == name }
+            status = installed ? "(installed: #{installed})" : "[install: hammer self:recipe install #{name}]"
+            line = "  #{name.ljust(width)}  # #{desc}"
+            Shell.say line
+            Shell.say "  #{' ' * width}    #{status}", :gray
+          end
+        end
+      end
+
+      # With no NAME: arrow-key picker. With NAME only: print the stub
+      # to stdout (user pipes it themselves). With NAME + TARGET: write
+      # the stub to TARGET and chmod +x in one shot.
+      def install(name, target = nil)
+        if name.nil?
+          names = Hammer::Recipe.all.keys.sort
+          if names.empty?
+            Shell.print_error 'no recipes available'
+            exit 1
+          end
+          idx = Shell.choose('pick a recipe to install', names)
+          exit 1 if idx.nil?
+          name = names[idx]
+        end
+
+        unless Hammer::Recipe.path(name)
+          Shell.print_error "unknown recipe: #{name}"
+          exit 1
+        end
+
+        stub = Hammer::Recipe.stub(name)
+        if target
+          path = File.expand_path(target)
+          File.write(path, stub)
+          File.chmod(0o755, path)
+          Shell.say "installed #{name} -> #{path}", :green
+        else
+          puts stub
+        end
+      end
+
+      def show(name)
+        path = Hammer::Recipe.path(name) or fail_unknown(name)
+        puts File.read(path)
+      end
+
+      def path(name)
+        path = Hammer::Recipe.path(name) or fail_unknown(name)
+        puts path
+      end
+
+      # For a gem recipe, offer to copy to user dir first so edits
+      # survive `hammer self:update`. Then exec $EDITOR on the file.
+      def edit(name)
+        path = Hammer::Recipe.path(name) or fail_unknown(name)
+        editor = ENV['EDITOR'] || ENV['VISUAL']
+        unless editor
+          Shell.print_error '$EDITOR not set'
+          exit 1
+        end
+
+        if path.start_with?(Hammer::Recipe::GEM_DIR)
+          user_dir = ENV['HAMMER_RECIPES_DIR'] || File.expand_path('~/.config/hammer/recipes')
+          target = File.join(user_dir, "#{name}.rb")
+          unless File.exist?(target)
+            if Shell.yes?("copy gem recipe to #{target} before editing? (recommended)")
+              require 'fileutils'
+              FileUtils.mkdir_p(user_dir)
+              FileUtils.cp(path, target)
+              Shell.say "copied to #{target}", :green
+              path = target
+            end
+          else
+            path = target
+          end
+        end
+
+        system(editor, path)
+      end
+
+      def fail_unknown(name)
+        Shell.print_error "unknown recipe: #{name}"
+        exit 1
+      end
+    end
+  end
+end

data/lib/hammer/recipe.rb

@@ -0,0 +1,92 @@
+class Hammer
+  # Discovery + helpers for "recipes" - standalone Hammerfile-style
+  # scripts shipped under `<gem>/recipes/` (and optionally the user's
+  # `~/.config/hammer/recipes/`) that are exposed as their own bin
+  # scripts in PATH via a tiny Ruby wrapper.
+  module Recipe
+    module_function
+
+    GEM_DIR ||= File.expand_path('../../recipes', __dir__)
+
+    # Recipe lookup directories, in priority order. User dir is only
+    # included when it exists. Honors HAMMER_RECIPES_DIR for overrides
+    # (mostly for tests).
+    def dirs
+      out = [GEM_DIR]
+      user = ENV['HAMMER_RECIPES_DIR'] || File.expand_path('~/.config/hammer/recipes')
+      out.unshift(user) if File.directory?(user)
+      out
+    end
+
+    # { "name" => "/abs/path/name.rb" }. User-dir entries win over gem
+    # entries because they come first in `dirs`.
+    def all
+      out = {}
+      dirs.each do |dir|
+        next unless File.directory?(dir)
+        Dir.glob(File.join(dir, '*.rb')).sort.each do |path|
+          name = File.basename(path, '.rb')
+          out[name] ||= path
+        end
+      end
+      out
+    end
+
+    # Path to the recipe file for `name`, or nil if unknown.
+    def path(name)
+      all[name.to_s]
+    end
+
+    # First `# desc: ...` line at the top of the file, or empty string.
+    # Cheap - reads only the first ~20 lines, no eval.
+    def desc(path)
+      return '' unless path && File.file?(path)
+      File.foreach(path).first(20).each do |line|
+        if (m = line.match(/\A#\s*desc:\s*(.+)$/i))
+          return m[1].strip
+        end
+      end
+      ''
+    end
+
+    # Ruby wrapper text printed by `hammer self:recipe 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 self:recipe install #{name} > ~/bin/#{name} && chmod +x $_
+        require 'lux-hammer'
+        Hammer.recipe('#{name}', ARGV)
+      RUBY
+    end
+
+    # If a stub for `name` is on PATH, return its absolute path. Detects
+    # by reading the file and looking for the literal `Hammer.recipe('<name>'`
+    # token - cheap and near-zero false positive.
+    def installed_path(name)
+      token = "Hammer.recipe('#{name}'"
+      ENV.fetch('PATH', '').split(File::PATH_SEPARATOR).each do |dir|
+        candidate = File.join(dir, name.to_s)
+        next unless File.file?(candidate) && File.executable?(candidate)
+        return candidate if File.read(candidate, 512).include?(token)
+      rescue StandardError
+        next
+      end
+      nil
+    end
+
+    # Group recipes by their source directory for the listing view.
+    # Returns [[source_label, { name => path }], ...].
+    def grouped
+      user_dir = ENV['HAMMER_RECIPES_DIR'] || File.expand_path('~/.config/hammer/recipes')
+      groups = { 'gem' => {}, 'user' => {} }
+      all.each do |name, path|
+        bucket = path.start_with?(user_dir) ? 'user' : 'gem'
+        groups[bucket][name] = path
+      end
+      groups.reject { |_, v| v.empty? }.to_a
+    end
+  end
+end