lux-hammer 0.3.13 → 0.3.14

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 411174afd97cefbe9e7e3309c25233f465b9458ee0dc710e67077725658876c0
-  data.tar.gz: f4b64f7897fd8c67412fdbe418ad51b96eeac1ebb3e87ce9df5b97651a4a9ff6
+  metadata.gz: 7ea304583caa18c45db8f340aecf5e08803f23eebe4f9152eefec7ac77c64b18
+  data.tar.gz: 72eafeef47b8ae8c2ff41e226756199f085865899532c3d7669dd5025c4b4019
 SHA512:
-  metadata.gz: ba1364fcff70fefa529a2e7586ee33f7826b43ee7cd3ebd5e454f0bce82131b427cf320d85d8d911edc3a11762196de7db9964c6877959548eb4c6753e5ac063
-  data.tar.gz: 5b21c08ac766b1af02b1a0d49b7fb3129fffd94b0c13fd07c7a5995851c21447e6a437848f25ef30f364bfccb94f1bac51046630dbbd574aaa109a61a738e893
+  metadata.gz: 7cfa688c6d9d21acc72a6c8d614acefe2942746fb8b8b55f4f72fb08d9f1d37a6eccbd3326551348ea572889e3404790c4a59f64577d394f257e1ab826959c45
+  data.tar.gz: 535fb35b15ae31e9e861ad0ff32d9e216382b533cb877b12560185cd722724c0d01a0dde350facebf209178166d88c4109328e7882ba6a14ae0273eb111d2215

data/.version

@@ -1 +1 @@
-0.3.13
+0.3.14

data/AGENTS.md

@@ -279,6 +279,9 @@ Task contracts:
   forward flags through). Bare invocation lists.
 * `h:init` - writes `Hammer::STARTER_HAMMERFILE` to `./Hammerfile`;
   refuses if one exists.
+* `h:json` - `puts JSON` of `root.export_spec` (tasks grouped exactly
+  like the bare listing via `section_for`, root group keyed `__root`).
+  `--all` keeps the `h:` tree, `--compact` minifies.
 
 The `:default` task and the `help` / `-h` / `--help` requests are
 invoked via `run_command(cmd, argv, full: name, quiet: true)` - the

data/README.md

@@ -562,6 +562,10 @@ Under the `h:` namespace:
 * `h:version` - print the lux-hammer version.
 * `h:recipes` - list / install / show / edit recipes.
 * `h:init` - write a starter Hammerfile in cwd (refuses if one exists).
+* `h:json` - dump the CLI definition as JSON (tasks grouped like the
+  bare listing, with desc/options/examples/aliases/needs); `--all`
+  includes the `h:` tasks, `--compact` minifies. Output is plain stdout
+  (the run banner goes to stderr), so `hammer h:json | jq` just works.
 
 Each is guarded by `unless commands.key?` within the namespace, so you
 can override one by reopening `namespace :h` in your Hammerfile.
@@ -574,6 +578,16 @@ hammer --system h:recipes              # list recipes, ignoring any local Hammer
 hammer --system h:recipes --install srt ~/bin/srt
 ```
 
+`--gui` opens a native macOS window for the current project: a sidebar of
+your tasks (grouped like the listing), a form per task built from its
+options, and a Run button that streams the task's output. It reads the
+project via `h:json` and runs each task as a `hammer <path> ...`
+subprocess. macOS / arm64 only.
+
+```sh
+hammer --gui                           # open the runner for the nearest Hammerfile
+```
+
 Customize bare `hammer` by replacing `:default`:
 
 ```ruby

data/gui/Hammer.app/Contents/Info.plist

@@ -0,0 +1,16 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>CFBundleName</key><string>Hammer</string>
+  <key>CFBundleDisplayName</key><string>Hammer</string>
+  <key>CFBundleIdentifier</key><string>com.lux-hammer.gui</string>
+  <key>CFBundleVersion</key><string>1</string>
+  <key>CFBundleShortVersionString</key><string>1.0</string>
+  <key>CFBundlePackageType</key><string>APPL</string>
+  <key>CFBundleExecutable</key><string>HammerGUI</string>
+  <key>LSMinimumSystemVersion</key><string>11.0</string>
+  <key>NSHighResolutionCapable</key><true/>
+  <key>NSPrincipalClass</key><string>NSApplication</string>
+</dict>
+</plist>

data/lib/hammer/builtins.rb

@@ -31,6 +31,7 @@ class Hammer
       register_version(h) unless h.commands.key?('version')
       register_recipes(h) unless h.commands.key?('recipes')
       register_init(h)    unless h.commands.key?('init')
+      register_json(h)    unless h.commands.key?('json')
     end
 
     def register_help(klass)
@@ -112,6 +113,29 @@ class Hammer
       end
     end
 
+    def register_json(klass)
+      klass.class_eval do
+        task :json do
+          desc <<~TXT
+            Dump the CLI definition as JSON: tasks grouped exactly like
+            the bare-`hammer` listing, each with desc, options, examples,
+            aliases, needs. Consumed by the macOS GUI and any tooling
+            that wants the full Hammerfile spec.
+          TXT
+          example 'h:json'
+          example 'h:json --all       # include the reserved h: tasks'
+          example 'h:json --compact   # minified, single line'
+          opt :all,     type: :boolean, desc: 'include reserved built-in h: tasks'
+          opt :compact, type: :boolean, desc: 'minified JSON (default: pretty)'
+          proc do |opts|
+            require 'json'
+            spec = self.class.root.export_spec(include_builtins: opts[:all])
+            puts opts[:compact] ? JSON.generate(spec) : JSON.pretty_generate(spec)
+          end
+        end
+      end
+    end
+
     # `:recipes` rolls all recipe-management actions into one task. Bare
     # invocation lists; opts pick the action and positional args carry
     # the recipe name (and optional target path for --install). Run via

data/lib/hammer/command.rb

@@ -63,6 +63,26 @@ class Hammer
       end
     end
 
+    # Structured form for JSON export (`h:json`). `path` is the full
+    # colon path supplied by the tree walk - a Command doesn't know its
+    # own namespace prefix. `hidden` follows the help rule: a task with
+    # no `desc` still dispatches but is hidden from listings.
+    def to_h(path = name)
+      {
+        name:      name,
+        path:      path,
+        desc:      desc,
+        brief:     brief,
+        hidden:    desc.empty?,
+        redefined: !prev_location.nil?,
+        location:  location,
+        alts:      alts,
+        needs:     needs,
+        examples:  examples,
+        options:   options.map(&:to_h)
+      }
+    end
+
     private
 
     def short_flag?(switch)

data/lib/hammer/option.rb

@@ -78,5 +78,24 @@ class Hammer
       return '' if default.nil?
       "(default: #{default.inspect})"
     end
+
+    # Structured form for JSON export (`h:json`). The GUI maps `type`
+    # to a form widget; `default`/`required`/`desc` decorate it. Mirrors
+    # the data behind `usage`. `negation` is only meaningful for booleans.
+    def to_h
+      h = {
+        name:        name.to_s,
+        type:        type.to_s,
+        default:     default,
+        required:    required,
+        desc:        desc,
+        placeholder: placeholder,
+        switch:      switch,
+        aliases:     aliases,
+        usage:       usage.strip
+      }
+      h[:negation] = negation if boolean?
+      h
+    end
   end
 end

data/lib/lux-hammer.rb

@@ -583,6 +583,39 @@ class Hammer
       end
     end
 
+    # Machine-readable spec for `h:json` -> the macOS GUI (and, later,
+    # for lux itself to render the default listing). One hash:
+    #   commands => { group => { full_path => task_meta } }
+    # Grouping/sort mirror the bare-`hammer` listing exactly: group by
+    # the first namespace segment (a bare task sharing a namespace's name
+    # joins that group via section_for), root tasks under "__root",
+    # "__root" first, remaining groups in first-encounter order, tasks
+    # within a group by [depth, name]. Hidden (no-`desc`) tasks are
+    # skipped and the reserved `h:` tree is pruned unless include_builtins.
+    def export_spec(include_builtins: false)
+      groups = {}   # group => { full_path => meta }, in first-encounter order
+
+      each_command(include_builtins: include_builtins) do |path, c|
+        next if c.desc.empty?
+        section = section_for(path, nil, self)
+        key = section == :root ? '__root' : section.to_s
+        (groups[key] ||= {})[path] = c.to_h(path)
+      end
+
+      sort_tasks = ->(h) { h.sort_by { |p, _| [p.count(':'), p] }.to_h }
+      ordered = {}
+      ordered['__root'] = sort_tasks.call(groups.delete('__root')) if groups.key?('__root')
+      groups.each { |k, v| ordered[k] = sort_tasks.call(v) }
+
+      {
+        schema:         1,
+        hammer_version: VERSION,
+        program_name:   program_name,
+        app_desc:       app_desc,
+        commands:       ordered
+      }
+    end
+
     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.
@@ -622,7 +655,9 @@ class Hammer
         end
       end
       parts.concat(positional)
-      Shell.say "> #{parts.join(' ')}", :gray
+      # Diagnostic, not program output - to stderr so stdout stays clean
+      # for machine-readable tasks (`h:json`, `h:version`) and pipes.
+      warn Shell.paint("> #{parts.join(' ')}", :gray)
     end
 
     # Fire `before` hooks from root down through the namespace chain.
@@ -703,7 +738,7 @@ class Hammer
         each_command(include_builtins: extended) { |path, c| print_full_block(path, c) unless c.desc.empty? }
       else
         Shell.say ''
-        print_command_list(self, include_builtins: extended)
+        print_command_list(include_builtins: extended)
       end
       print_recipes_section if extended && root.instance_variable_get(:@hammer_binary)
       print_extras if extended
@@ -736,8 +771,8 @@ class Hammer
       Shell.say "Usage: #{program_name} #{prefix}:COMMAND [ARGS]", :cyan
       rows = []
       sibling = find_namespace_sibling(prefix)
-      rows << [prefix, sibling] if sibling && !sibling.desc.empty?
-      ns.each_command(prefix) { |path, c| rows << [path, c] unless c.desc.empty? }
+      rows << [prefix, sibling.to_h(prefix)] if sibling && !sibling.desc.empty?
+      ns.each_command(prefix) { |path, c| rows << [path, c.to_h(path)] unless c.desc.empty? }
       unless rows.empty?
         Shell.say ''
         Shell.say 'Commands:', :yellow
@@ -802,38 +837,30 @@ class Hammer
       Shell.say Hammer::STARTER_HAMMERFILE
     end
 
-    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, 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
-      # leaf name. Bare leaves go in :root.
-      groups = rows.group_by { |full, _| section_for(full, prefix, klass) }
-      width  = rows.map { |full, _| full.length }.max
-      first  = true
-
-      if (rooted = groups.delete(:root))
-        Shell.say 'Commands:', :yellow
-        emit_rows(rooted.sort_by { |full, _| [full.count(':'), full] }, width)
-        first = false
-      end
-
-      groups.each do |section, items|
-        Shell.say unless first
-        first = false
-        Shell.say "#{section}:", :yellow
-        emit_rows(items.sort_by { |full, _| [full.count(':'), full] }, width)
+    # Pure rendering off `export_spec` - the same grouped structure
+    # `h:json` emits, so the listing and the JSON can never drift.
+    # `export_spec` already does the work: drops hidden (no-`desc`)
+    # tasks, prunes the `h:` tree unless include_builtins, groups by
+    # first namespace segment ("__root" for bare tasks), orders "__root"
+    # first, and sorts each group by [depth, name].
+    def print_command_list(include_builtins: true)
+      groups = export_spec(include_builtins: include_builtins)[:commands]
+      return if groups.empty?
+
+      width = groups.values.flat_map(&:keys).map(&:length).max
+      groups.each_with_index do |(section, tasks), i|
+        Shell.say unless i.zero?
+        Shell.say(section == '__root' ? 'Commands:' : "#{section}:", :yellow)
+        emit_rows(tasks.to_a, width)
       end
     end
 
+    # `rows` is an array of [full_path, task_meta] - the per-task hashes
+    # from `Command#to_h` (also used to render namespace listings).
     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
+      rows.each do |full, t|
+        brief = t[:alts].empty? ? t[:brief] : "#{t[:brief]} (alt: #{t[:alts].join(', ')})"
+        brief = "#{brief} #{Shell.paint('(redefined)', :yellow)}" if t[:redefined]
         Shell.say "  #{program_name} #{full.ljust(width)}  # #{brief}"
       end
     end
@@ -1047,6 +1074,7 @@ class Hammer
   def self.cli(argv = ARGV)
     argv = argv.dup
     force_system = !!argv.delete('--system')
+    launch_gui   = !!argv.delete('--gui')
 
     # Shebang invocation: `hammer /path/to/script ...args` (kernel passes
     # the script path as argv[0] for `#!/usr/bin/env hammer` files).
@@ -1060,6 +1088,12 @@ class Hammer
     end
 
     path = force_system ? nil : find_hammerfile(Dir.pwd)
+
+    # `hammer --gui` opens the native macOS runner pointed at this project
+    # (the Hammerfile's dir, or cwd when none was found). The CLI just
+    # launches the bundled app and returns.
+    return launch_gui!(path ? File.dirname(path) : Dir.pwd) if launch_gui
+
     unless path
       # No Hammerfile (or --system) - all built-ins are reachable. Bare
       # `hammer`, `hammer h:recipes`, `hammer h:update`, `hammer h:agents`,
@@ -1188,4 +1222,21 @@ class Hammer
     end
   end
 
+  # Spawn the vendored macOS GUI (gui/Hammer.app), pointed at the project
+  # dir and this hammer binary. Launched directly (not via `open`) so it
+  # inherits the caller's environment - the GUI shells back out to this
+  # same `hammer` for `h:json` and task runs, and that needs the same PATH.
+  def self.launch_gui!(project_dir)
+    bin = File.expand_path('../gui/Hammer.app/Contents/MacOS/HammerGUI', __dir__)
+    unless File.executable?(bin)
+      Shell.print_error "GUI app not found at #{bin}"
+      Shell.say 'build it: ./gui/HammerGUI/build_app.sh', :yellow
+      exit 1
+    end
+    hammer_bin = (File.realpath($PROGRAM_NAME) rescue File.expand_path($PROGRAM_NAME))
+    pid = Process.spawn(bin, '--project', File.expand_path(project_dir), '--hammer', hammer_bin)
+    Process.detach(pid)
+    Shell.say "launched Hammer GUI for #{project_dir} (pid #{pid})", :green
+  end
+
 end

data/recipes/git-helper.rb

@@ -142,8 +142,8 @@ helpers do
       if message.empty?
         run 'git reset --mixed'
         exit
-      elsif message.length < 5
-        say 'Please add better commit message, min length 5 chars', :red
+      elsif message.length < 1
+        say 'Please add better commit message, min length 1 chars', :red
         next
       else
         bump_version

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: lux-hammer
 version: !ruby/object:Gem::Version
-  version: 0.3.13
+  version: 0.3.14
 platform: ruby
 authors:
 - Dino Reic
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-06-05 00:00:00.000000000 Z
+date: 2026-06-27 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: minitest
@@ -36,6 +36,8 @@ files:
 - "./AGENTS.md"
 - "./README.md"
 - "./bin/hammer"
+- "./gui/Hammer.app/Contents/Info.plist"
+- "./gui/Hammer.app/Contents/MacOS/HammerGUI"
 - "./lib/hammer/builder.rb"
 - "./lib/hammer/builtins.rb"
 - "./lib/hammer/command.rb"