lux-hammer 0.3.10 → 0.3.13

data/lib/lux-hammer.rb

@@ -94,8 +94,8 @@ class Hammer
       # If the method takes no args, call it without opts. Otherwise pass
       # opts. So both `def build` and `def build(opts)` work.
       m = method_name
-      arity = instance_method(method_name).arity
-      cmd.handler = arity.zero? ? proc { send(m) } : proc { |opts| send(m, opts) }
+      takes_arg = instance_method(method_name).parameters.any? { |type, _| %i[req opt rest].include?(type) }
+      cmd.handler = takes_arg ? proc { |opts| send(m, opts) } : proc { send(m) }
       cmd.finalize!
       commands[cmd.name] = cmd
 
@@ -164,7 +164,11 @@ class Hammer
       end
       cmd.handler = handler
 
-      if (prev = commands[cmd.name])
+      # Only warn when overriding a task that was also defined inside the
+      # main app. Overriding one that came from outside - a framework
+      # default, plugin, or gem - is an intentional override, so stay quiet
+      # and don't tag it `(redefined)` in help.
+      if (prev = commands[cmd.name]) && app_local_location?(prev.location)
         cmd.prev_location = prev.location
         warn_redefinition('task', cmd.name, prev.location, cmd.location)
       end
@@ -190,28 +194,29 @@ class Hammer
     #     namespace :users do ... end
     #   end
     #
+    # Reopening a namespace merges: the same `namespace :db do ... end` can
+    # be split across files (Rake-style) and the blocks accumulate onto one
+    # subclass. Only a duplicate *task* name inside warns - that's handled
+    # by `task`. The namespace subclass is created lazily on first mention.
     def namespace(name, &block)
-      sub = Class.new(Hammer)
-      # Track the top-level CLI class so cross-invocation
-      # (`hammer 'ns:cmd'`) from inside a namespaced command dispatches
-      # against the full tree, not just the current namespace.
-      sub.instance_variable_set(:@root, root)
-      # Parent link, so `before` hooks defined further up the namespace
-      # tree can be collected and run outer -> inner before a command.
-      sub.instance_variable_set(:@parent, self)
-      # Share the parent's resolved program_name so help banners show
-      # "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
+      sub = (@namespaces[name.to_s] ||= begin
+        ns = Class.new(Hammer)
+        # Track the top-level CLI class so cross-invocation
+        # (`hammer 'ns:cmd'`) from inside a namespaced command dispatches
+        # against the full tree, not just the current namespace.
+        ns.instance_variable_set(:@root, root)
+        # Parent link, so `before` hooks defined further up the namespace
+        # tree can be collected and run outer -> inner before a command.
+        ns.instance_variable_set(:@parent, self)
+        # Share the parent's resolved program_name so help banners show
+        # "myapp ns:cmd" with the same prefix everywhere - and so the value
+        # captured pre-chdir (see `Hammer.cli`) survives into nested classes.
+        ns.instance_variable_set(:@program_name, program_name)
+        ns.instance_variable_set(:@location, source_location_of(block))
+        ns
+      end)
 
-      @namespaces[name.to_s] = sub
+      Hammer.with_target(sub) { sub.class_eval(&block) } if block
     end
 
     # Register a hook to run before every command in this class (root or
@@ -252,7 +257,23 @@ class Hammer
     # built-in C-defined procs, eval'd blocks).
     def source_location_of(block)
       loc = block&.source_location
-      loc ? "#{loc[0]}:#{loc[1]}" : '(unknown)'
+      loc ? "#{relativize_path(loc[0])}:#{loc[1]}" : '(unknown)'
+    end
+
+    # Trim the cwd prefix off an absolute path so redefinition warnings
+    # read as `./lib/tasks/foo.rb` instead of a long absolute path. Paths
+    # outside cwd (framework / gem files) are left absolute.
+    def relativize_path(path)
+      prefix = "#{Dir.pwd}/"
+      path.start_with?(prefix) ? ".#{path[Dir.pwd.length..]}" : path
+    end
+
+    # True when a captured location lives inside the main app. relativize_path
+    # rewrites in-app absolute paths to a `.`-relative form, so anything still
+    # starting with "/" is an absolute path outside cwd - a framework, plugin,
+    # or gem file. Relative locations are already cwd-anchored, hence local.
+    def app_local_location?(loc)
+      !loc.to_s.start_with?('/')
     end
 
     # Emit a yellow [hammer] warning on stderr when a task/namespace is
@@ -392,6 +413,13 @@ class Hammer
         return print_help
       end
 
+      # An exact namespace beats a fuzzy command match, so `hammer h` lists
+      # the `h:` namespace instead of prefix-matching some `h...` command.
+      if !commands.key?(name) && namespaces.key?(name)
+        ns, canonical = resolve_namespace(name)
+        return print_namespace_help(canonical, ns)
+      end
+
       cmd, owner, canonical = resolve(name)
       return owner.run_command(cmd, argv, full: canonical) if cmd
 
@@ -497,6 +525,7 @@ class Hammer
     # Tries prefix match first, then substring; raises AmbiguousMatch
     # when either pass hits more than one item.
     def fuzzy_pick(name, items, kind, &keys_for)
+      return nil if name.empty?
       [:start_with?, :include?].each do |op|
         matches = items.select { |item| keys_for.call(item).any? { |k| k.send(op, name) } }
         next if matches.empty?
@@ -527,21 +556,30 @@ class Hammer
       opts.each do |k, v|
         next if v == false
         flag = "--#{k.to_s.tr('_', '-')}"
-        argv << (v == true ? flag : "#{flag}=#{v}")
+        if v == true
+          argv << flag
+        else
+          argv << "#{flag}=#{v.is_a?(Array) ? v.join(',') : v}"
+        end
       end
       start(argv)
     end
 
     # Yield [full_colon_path, Command] for every command in this class
-    # and all nested namespaces.
-    def each_command(prefix = nil, &block)
+    # and all nested namespaces. `include_builtins: false` prunes
+    # namespaces flagged `@builtin_namespace` (the reserved `h:` tree) -
+    # used so the compact listing hides built-ins outside `--help`. Only
+    # affects descent from a parent; iterating a flagged namespace
+    # directly (e.g. `hammer h:`) still lists its own commands.
+    def each_command(prefix = nil, include_builtins: true, &block)
       commands.each_value do |c|
         full = prefix ? "#{prefix}:#{c.name}" : c.name
         yield full, c
       end
       namespaces.each do |ns_name, sub|
+        next if !include_builtins && sub.instance_variable_get(:@builtin_namespace)
         sub_prefix = prefix ? "#{prefix}:#{ns_name}" : ns_name
-        sub.each_command(sub_prefix, &block)
+        sub.each_command(sub_prefix, include_builtins: include_builtins, &block)
       end
     end
 
@@ -580,7 +618,7 @@ class Hammer
         if o.boolean?
           parts << (val ? "--#{o.name}" : "--no-#{o.name}")
         else
-          parts << "--#{o.name}=#{val}"
+          parts << "--#{o.name}=#{val.is_a?(Array) ? val.join(',') : val}"
         end
       end
       parts.concat(positional)
@@ -591,6 +629,9 @@ class Hammer
     # Each class's hooks fire at most once per top-level `start`, so
     # prereqs dispatched via `needs` won't re-trigger them.
     def run_before_hooks(instance, opts)
+      # Built-in `h:` meta-commands parent to the project root but must not
+      # trigger the project's own `before` hooks (dotenv, env checks, ...).
+      return if instance_variable_get(:@builtin_namespace)
       ran = Thread.current[:hammer_before_ran] ||= {}
       ancestor_chain.each do |klass|
         next if ran[klass.object_id]
@@ -640,15 +681,29 @@ class Hammer
 
       print_top_banner
       Shell.say "Usage: #{program_name} COMMAND [ARGS]", :cyan
+      # Compact (bare-invocation) view only - the extended `--help` view
+      # already IS the full usage, so don't nag about it there.
+      unless extended
+        Shell.say "add `--help` to show usage help", :gray
+        # No project Hammerfile + no custom tasks loaded: point the user at
+        # `h:init`. The flag is set by `Hammer.cli` when the lookup misses.
+        if instance_variable_get(:@no_hammerfile)
+          Shell.say "no Hammerfile found in #{Dir.pwd} - run `#{program_name} h:init` to create one", :gray
+        end
+      end
       if @app_desc && !@app_desc.empty?
         Shell.say ''
         @app_desc.each_line { |l| Shell.say "  #{l.chomp}" }
       end
+      # Built-in `h:` commands only surface in the extended view
+      # (`--help` / `-h` / `help`); the bare-invocation listing stays
+      # focused on the project's own tasks. They remain dispatchable
+      # regardless - this only governs what the listing shows.
       if expanded
-        each_command { |path, c| print_full_block(path, c) unless c.desc.empty? }
+        each_command(include_builtins: extended) { |path, c| print_full_block(path, c) unless c.desc.empty? }
       else
         Shell.say ''
-        print_command_list(self)
+        print_command_list(self, include_builtins: extended)
       end
       print_recipes_section if extended && root.instance_variable_get(:@hammer_binary)
       print_extras if extended
@@ -667,7 +722,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} recipes --install #{name}]"
+        suffix = installed ? "(installed: #{installed})" : "[install: #{program_name} h:recipes --install #{name}]"
         Shell.say "  #{name.ljust(width)}  # #{desc}"
         Shell.say "  #{' ' * width}    #{suffix}", :gray
       end
@@ -735,24 +790,24 @@ class Hammer
 
     def print_footer
       Shell.say ''
-      Shell.say "powered by hammer - #{HOMEPAGE}", :gray
+      Shell.say "powered by hammer (v#{VERSION}) - #{HOMEPAGE}", :gray
     end
 
     # 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`.
+    # `Hammer::STARTER_HAMMERFILE`. For exhaustive docs see `hammer h:agents`.
     def print_hammerfile_example
       Shell.say ''
       Shell.say 'Hammerfile example:', :yellow
       Shell.say Hammer::STARTER_HAMMERFILE
     end
 
-    def print_command_list(klass, prefix = nil)
+    def print_command_list(klass, prefix = nil, include_builtins: true)
       rows = []
       # Commands without a `desc` are hidden from listings but still
       # dispatchable + `hammer`-callable - useful for private helpers
       # invoked from `before` hooks or other commands (e.g. `:env`, `:app`).
-      klass.each_command(prefix) { |full, c| rows << [full, c] unless c.desc.empty? }
+      klass.each_command(prefix, include_builtins: include_builtins) { |full, c| rows << [full, c] unless c.desc.empty? }
       return if rows.empty?
 
       # group by "section" = everything between the view prefix and the
@@ -890,7 +945,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 recipes` to list with descriptions', :gray
+      Shell.say 'try `hammer h:recipes` to list with descriptions', :gray
       exit 1
     end
 
@@ -946,12 +1001,12 @@ class Hammer
     end
   RUBY
 
-  # Default install dir used by install.sh and `hammer update`.
+  # Default install dir used by install.sh and `hammer h: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 h: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
@@ -1007,15 +1062,17 @@ class Hammer
     path = force_system ? nil : find_hammerfile(Dir.pwd)
     unless path
       # No Hammerfile (or --system) - all built-ins are reachable. Bare
-      # `hammer`, `hammer recipes`, `hammer update`, `hammer agents`,
-      # `hammer version`, `hammer init` all work.
+      # `hammer`, `hammer h:recipes`, `hammer h:update`, `hammer h:agents`,
+      # `hammer h:version`, `hammer h: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)
+        # No project Hammerfile was found - only built-ins are loaded. The
+        # bare-invocation help uses this to note that no Hammerfile exists.
+        klass.instance_variable_set(:@no_hammerfile, true)
         klass.program_name
         require_relative 'hammer/builtins'
-        Hammer::Builtins.register_core(klass)
-        Hammer::Builtins.register_no_project(klass)
+        Hammer::Builtins.register(klass)
         klass.start(argv)
         return
       end
@@ -1039,8 +1096,8 @@ class Hammer
       Shell.say STARTER_HAMMERFILE
       Shell.say ''
       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
+      Shell.say "tip: run `#{bin} h:init` to drop the example above into ./Hammerfile", :gray
+      Shell.say "tip: run `#{bin} h:agents` for AI-friendly Hammerfile authoring docs", :gray
       exit 1
     end
 
@@ -1061,14 +1118,13 @@ class Hammer
     # are NOT visible during Hammerfile evaluation, only inside handlers.
     Hammer::Dotenv.load(Dir.pwd) if klass.dotenv_enabled?
 
-    # 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.
+    # Built-ins register AFTER Hammerfile eval so user-defined tasks win
+    # (the `unless commands.key?(...)` guards skip a built-in when the
+    # Hammerfile already owns the name - no redefinition warning). All
+    # built-ins live under `h:`, so they can't collide with project root
+    # tasks and the full set registers in every context.
     require_relative 'hammer/builtins'
-    Hammer::Builtins.register_core(klass)
+    Hammer::Builtins.register(klass)
 
     klass.start(argv)
   end
@@ -1088,7 +1144,7 @@ class Hammer
   end
 
   # Evaluate a shebang script as a self-contained CLI. Mirrors `recipe`
-  # semantics: no chdir, no `@hammer_binary` flag, no `register_core`
+  # semantics: no chdir, no `@hammer_binary` flag, no `Builtins.register`
   # built-ins (so the script's `--help` shows only what it defines).
   # `program_name` is the script's basename so help reads "myscript foo"
   # rather than "hammer foo" - works even when invoked via a symlink in
@@ -1110,15 +1166,14 @@ class Hammer
     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
+  # True if argv targets the reserved `h:` built-in namespace (`h`, `h:`,
+  # `h:update`, ...). Used in the no-Hammerfile branch to wake up the
+  # built-ins for invocations like `hammer h: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}:") }
+    first == 'h' || first.start_with?('h:')
   end
 
   # Walk up the directory tree looking for a Hammerfile.

data/recipes/deploy.rb

@@ -0,0 +1,32 @@
+#!/usr/bin/env hammer
+# desc: SSH/rsync deploy - Caddy + systemd + atomic releases
+
+desc <<~TXT
+  Stupid-simple SSH/rsync deploy (Caddy + systemd + atomic releases).
+
+  Quickstart:
+    deploy app:init          # copy templates into ./config/deploy/
+    deploy doctor            # check & prep the host
+    deploy up                # deploy current branch
+
+  Server:
+    deploy server:log        # tail the systemd journal
+    deploy server:ssh        # shell into the current release
+    deploy server:restart    # restart the web service
+    deploy log --log errors  # dump a remote log
+TXT
+
+# Loads the bundled lib (config/ssh/template/doctor/context/manifest/
+# commands/hammer) - same require chain the gem's lib/lux_deploy.rb had.
+require_relative 'lib/deploy/boot'
+
+# Auto-load the app's deploy bootstrap, if present, before tasks fire.
+# A consumer can inject Ruby (e.g. a pre-deploy hook) without writing a
+# custom Hammerfile.
+init = File.join(Dir.pwd, 'config', 'deploy', 'init.rb')
+load init if File.file?(init)
+
+# `self` here is the recipe's Builder context - same surface a Hammerfile
+# gets. Pass templates_dir explicitly since there's no gem ROOT to fall
+# back to; it resolves to recipes/lib/deploy/templates.
+LuxDeploy::Hammer.register(self, templates_dir: File.join(__dir__, 'lib/deploy/templates'))

data/recipes/lib/deploy/boot.rb

@@ -0,0 +1,52 @@
+require 'fileutils'
+require 'pathname'
+require 'open3'
+require 'set'
+require 'shellwords'
+require 'yaml'
+
+module LuxDeploy
+  # Recipe layout: this file and its siblings live under
+  # recipes/lib/deploy/, so ROOT points here and `templates/` sits
+  # right next to us (no gem root anymore).
+  ROOT ||= Pathname.new(__dir__)
+  VERSION ||= '0.2.0'
+
+  # Branches that select `.env` instead of `.env.staging`.
+  MAIN_BRANCHES ||= %w[master main]
+
+  # Server-side conventions. Not config-tunable because doctor and the
+  # deploy flow both hardcode these paths in the host setup. A different
+  # caddy/systemd layout means a different recipe.
+  PORT_RANGE  ||= (3010..3990).step(10).to_a
+  CADDY_SITES ||= '/etc/caddy/sites'
+  SYSTEMD_DIR ||= '/etc/systemd/system'
+
+  class Error < StandardError
+    def to_s
+      "ERROR: #{super}"
+    end
+  end
+
+  # Host-supplied defaults that sit under the user's .yaml. Set once by a
+  # wrapping plugin/Hammerfile (e.g. lux-fw seeds 'lux-web' / 'lux-apps'),
+  # consumed by Config.new. Empty by default so the recipe stays "generic".
+  @defaults = {}
+
+  class << self
+    attr_reader :defaults
+
+    def set_defaults(hash)
+      @defaults = (hash || {}).each_with_object({}) { |(k, v), h| h[k.to_s] = v }
+    end
+  end
+end
+
+require_relative 'config'
+require_relative 'ssh'
+require_relative 'template'
+require_relative 'doctor'
+require_relative 'context'
+require_relative 'manifest'
+require_relative 'commands'
+require_relative 'hammer'