lux-hammer 0.3.12 → 0.3.14

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 75362aef2908fdd2a3f4e32ab8c6ce7a4c4ae52fce795f5bca5437325a92da49
-  data.tar.gz: 0d318814ed2cdd0da35ca2b66e7637c62d5d2efece0cb24f60da1c5e02f4ad1f
+  metadata.gz: 7ea304583caa18c45db8f340aecf5e08803f23eebe4f9152eefec7ac77c64b18
+  data.tar.gz: 72eafeef47b8ae8c2ff41e226756199f085865899532c3d7669dd5025c4b4019
 SHA512:
-  metadata.gz: 64a8ce40bf7fc4986b6b0796c72fb9a8e9a13b2acb70c4aaa76cd68d5f68158bc9fbde7d5a0a5f3e586978b97f849f712b5addef336754b896e901f71c9feec2
-  data.tar.gz: 6f12a27b72098ff513ecc216ee8f2c6deb08e3c3a29cf4f1a7e9c6dfb7750a9b00ad13fe514f66fdda7b7a837b62e2526d1af04ca1af85deed1435e2d34b30a3
+  metadata.gz: 7cfa688c6d9d21acc72a6c8d614acefe2942746fb8b8b55f4f72fb08d9f1d37a6eccbd3326551348ea572889e3404790c4a59f64577d394f257e1ab826959c45
+  data.tar.gz: 535fb35b15ae31e9e861ad0ff32d9e216382b533cb877b12560185cd722724c0d01a0dde350facebf209178166d88c4109328e7882ba6a14ae0273eb111d2215

data/.version

@@ -1 +1 @@
-0.3.12
+0.3.14

data/AGENTS.md

@@ -156,17 +156,18 @@ Runtime cross-invocation:
   errors if none found anywhere up the tree (unless the invocation
   routes to a built-in - see `dispatches_to_builtin?` /
   `looks_like_builtin?`, true for bare invocation / leading flag /
-  explicit help / a built-in task name). After evaluating the
-  Hammerfile, registers the always-on core built-ins (`:default`,
-  `:help`, `:update`, `:agents`, `:version`) via
-  `Hammer::Builtins.register_core` - each guarded by
-  `unless commands.key?(...)` so a user-defined task wins silently.
-  No-project-only built-ins (`:recipes`, `:init`) are NOT registered
-  when a Hammerfile loaded - reach them with `--system`. The
-  `--system` flag is peeled off argv at the top and forces the
-  no-Hammerfile branch. Not part of the user-facing surface - don't
-  recommend it in examples; `Hammer.run` is what library users should
-  reach for.
+  explicit help / an `h:`-namespace path). After evaluating the
+  Hammerfile, registers the built-ins via `Hammer::Builtins.register`:
+  `:default` at the root (backs bare invocation, carries `--version`)
+  plus the `h:` namespace (`h:help`, `h:update`, `h:agents`,
+  `h:version`, `h:recipes`, `h:init`). The full set registers in every
+  context - living under `h:` means they can't collide with project
+  root tasks, so there's no core/no-project split. Each is guarded by
+  `unless commands.key?(...)` so a user who reopens `namespace :h` wins
+  silently. The `--system` flag is peeled off argv at the top and
+  forces the no-Hammerfile branch. 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,
@@ -239,45 +240,53 @@ explicit ADR-level discussion. Keys:
 
 ## Built-in tasks (user-overridable)
 
-`Hammer::Builtins` defines two registration entry points; both register
-**after** Hammerfile evaluation and skip each task when the user
-already defined it (`unless klass.commands.key?(name)` - no
-redefinition warning).
-
-* `register_core(klass)` - always called. Registers `:default`,
-  `:help`, `:update`, `:agents`, `:version`. These coexist with
-  Hammerfile tasks.
-* `register_no_project(klass)` - called only on the no-Hammerfile
-  branch of `Hammer.cli` (which `--system` also routes through).
-  Registers `:recipes` and `:init` - tasks that would collide too
-  easily with user tasks inside a project.
-
-No reserved namespace. Names like `:self`, `:recipes`, `:update` can
-all be defined freely in a Hammerfile; the built-ins yield.
+`Hammer::Builtins.register(klass)` is the single registration entry
+point. It runs **after** Hammerfile evaluation and skips each task when
+the user already defined it (`unless commands.key?(name)` - no
+redefinition warning). The same set registers in every context (project
+or bare binary): `:default` at the root, everything else under the
+reserved `h:` namespace.
+
+* Root: `:default` (hidden, carries `--version` / `-v`).
+* `h:` namespace: `h:help`, `h:update`, `h:agents`, `h:version`,
+  `h:recipes`, `h:init`.
+
+`h:` is the reserved built-in namespace - keeping the tool-meta commands
+there means they never collide with a project's root tasks, so there's
+no core/no-project split and no hidden-desc bookkeeping. Other names
+(`:self`, `:recipes` at the root, ...) stay free for Hammerfiles. The
+`h:` subclass is flagged `@builtin_namespace`, which prunes it from the
+compact listing - the built-ins are always dispatchable but only show
+(under an `h:` section) in the extended `--help` view.
 
 Task contracts:
 
-* `:default` - hidden (no desc). Just prints `self.class.root.print_help`
-  (brief). Fires for bare `hammer` and leading-flag invocations where
-  the first token starts with `-` and isn't `-h` / `--help` (see
+* `:default` - hidden (no desc), at the root. Prints
+  `self.class.root.print_help` (brief) and exposes a `--version` flag.
+  Fires for bare `hammer` and leading-flag invocations where the first
+  token starts with `-` and isn't `-h` / `--help` (see
   `Hammer.dispatch`). User overrides typically declare flag opts and
   fall through to `hammer :help` when none matched.
-* `:help` - has a desc, shows in listings. Calls
-  `self.class.root.print_help(opts[:args].first, extended: true)`.
-  Fires for `help` / `-h` / `--help` at the top level.
-* `:update` / `:agents` / `:version` - thin wrappers around
+* `h:help` - has a desc; shows in the `--help` listing. Calls
+  `self.class.root.print_help(opts[:args].first, extended: true)`. The
+  conventional `help` / `-h` / `--help` at the top level still reach it
+  (handled directly in `Hammer.dispatch`).
+* `h:update` / `h:agents` / `h:version` - thin wrappers around
   `Hammer.self_update` / `Hammer.print_ai_help` / `puts Hammer::VERSION`.
-* `:recipes` - all recipe-management actions on one task, picked via
+* `h:recipes` - all recipe-management actions on one task, picked via
   boolean opts: `--install [NAME [TARGET]]`, `--show NAME`,
   `--path NAME`, `--edit NAME`, `--run NAME [ARGS]` (use `--` to
   forward flags through). Bare invocation lists.
-* `:init` - writes `Hammer::STARTER_HAMMERFILE` to `./Hammerfile`;
+* `h:init` - writes `Hammer::STARTER_HAMMERFILE` to `./Hammerfile`;
   refuses if one exists.
-
-Both `:default` and `:help` are invoked via `run_command(cmd, argv,
-full: name, quiet: true)` - the gray `> prog cmd ...` banner is
-suppressed because the user didn't type `hammer default` /
-`hammer help` literally.
+* `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
+gray `> prog cmd ...` banner is suppressed because the user didn't type
+`hammer default` / `hammer h:help` literally.
 * Commands listed flat with colon paths, grouped by top-level namespace.
 * Bare namespace (`hammer db`) prints the same listing scoped to that
   namespace.

data/README.md

@@ -73,7 +73,7 @@ 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
+hammer h:update   # git pull main + rebuild + reinstall
 ```
 
 ## Quick start
@@ -537,41 +537,57 @@ end
 `hammer` and `hammer db` won't list `env`, but `hammer env`,
 `hammer :env` from another proc, and `before { hammer :env }` all work.
 
-## Built-in tasks (all overridable)
+## Built-in tasks
 
-The `hammer` binary auto-registers a small set of built-in tasks at
-the root of your CLI. Each one is guarded by `unless commands.key?` -
-defining your own `task :name` in a Hammerfile silently replaces the
-built-in.
+The `hammer` binary auto-registers a small set of built-in tasks. All
+the tool-meta commands live under the reserved `h:` namespace so they
+can never collide with your project's own root tasks. They register the
+same way with or without a Hammerfile and are always dispatchable, but
+to keep the bare listing focused on your project they only show up
+(under an `h:` section) in the extended `hammer --help` view.
 
-Always available (with or without a Hammerfile):
+Handled at the root (so the conventional invocations keep working):
 
 * `:default` - fires on bare `hammer` and on leading-flag invocations.
-  Hidden from listings. Just prints the brief help by default; override
-  to wire up your own global flags.
-* `:help` - `hammer help [TARGET]`, `hammer -h`, `hammer --help`. Prints
-  the extended help view; `TARGET` accepts a command path or a `ns:`
-  prefix.
-* `:update` - rebuild + reinstall lux-hammer from main.
-* `:agents` - dump AGENTS.md (AI-friendly Hammerfile authoring docs).
-* `:version` - print the lux-hammer version.
+  Hidden from listings. Prints the brief help by default and carries a
+  `--version` / `-v` flag; override to wire up your own global flags.
+* `hammer help [TARGET]`, `hammer -h`, `hammer --help` - prints the
+  extended help view; `TARGET` accepts a command path or a `ns:` prefix.
+  (Also available as `hammer h:help`.)
+
+Under the `h:` namespace:
+
+* `h:update` - rebuild + reinstall lux-hammer from main.
+* `h:agents` - dump AGENTS.md (AI-friendly Hammerfile authoring docs).
+* `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.
 
-Only when no Hammerfile is loaded (or `--system` is passed - see below):
+`--system` forces the no-Hammerfile branch - the Hammerfile in the
+current tree (if any) isn't loaded for that invocation:
 
-* `:recipes` - list / install / show / edit recipes.
-* `:init` - write a starter Hammerfile in cwd (refuses if one exists).
+```sh
+hammer --system h:recipes              # list recipes, ignoring any local Hammerfile
+hammer --system h:recipes --install srt ~/bin/srt
+```
 
-These two are skipped inside a project so they don't shadow user tasks.
-To reach them from inside a project, pass `--system`:
+`--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 --system recipes              # list recipes from anywhere
-hammer --system recipes --install srt ~/bin/srt
+hammer --gui                           # open the runner for the nearest Hammerfile
 ```
 
-`--system` forces the no-Hammerfile branch - the Hammerfile in the
-current tree (if any) isn't loaded for that invocation.
-
 Customize bare `hammer` by replacing `:default`:
 
 ```ruby
@@ -1106,20 +1122,21 @@ A **recipe** is a standalone Hammerfile-style script bundled inside the
 top-level binary in your `PATH` - so `srt` becomes a real command, not
 `hammer srt:shift`.
 
-Recipe management lives under the `recipes` task. From inside a
-project the task isn't registered (so it can't shadow user tasks);
-pass `--system` to reach it from anywhere.
+Recipe management lives under the `h:recipes` task, reachable from
+anywhere (inside a project the `h:` namespace can't shadow your root
+tasks). `--system` skips loading a local Hammerfile if you want a clean
+environment.
 
 Listing what's available:
 
 ```sh
-$ hammer recipes                    # from any non-project dir
-$ hammer --system recipes           # from inside a project
+$ hammer h:recipes                    # from any directory
+$ hammer --system h:recipes           # ignoring any local Hammerfile
 gem:
   srt  # Subtitle (.srt) toolkit - shift timestamps, show stats
-         [install: hammer recipes --install srt]
+         [install: hammer h:recipes --install srt]
   llm  # personal LLM utility CLI (memory store, prompt-token expander, ...)
-         [install: hammer recipes --install llm]
+         [install: hammer h:recipes --install llm]
 ```
 
 Installing one. With no TARGET, the stub is printed to stdout (you
@@ -1127,8 +1144,8 @@ redirect it yourself); with a TARGET path, lux-hammer writes the file
 and chmods +x in one step:
 
 ```sh
-$ hammer recipes --install srt ~/bin/srt    # write + chmod
-$ hammer recipes --install srt > ~/bin/srt && chmod +x ~/bin/srt
+$ hammer h:recipes --install srt ~/bin/srt    # write + chmod
+$ hammer h:recipes --install srt > ~/bin/srt && chmod +x ~/bin/srt
 $ srt --help
 Usage: srt COMMAND [ARGS]
 
@@ -1145,7 +1162,7 @@ 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 recipes`. The file body
+`# desc: ...` comment is what shows in `hammer h:recipes`. The file body
 uses the same DSL as a Hammerfile - `task`, `namespace`, `before`,
 `load`. Example `~/.config/hammer/recipes/json.rb`:
 
@@ -1165,22 +1182,22 @@ end
 Install it the same way:
 
 ```sh
-$ hammer recipes --install json ~/bin/json
+$ hammer h:recipes --install json ~/bin/json
 ```
 
 User-dir recipes override gem recipes with the same name, so you can
 fork without forking.
 
-### Other `recipes` actions
+### Other `h:recipes` actions
 
 ```sh
-hammer recipes                            # list all
-hammer recipes --install                  # interactive picker, then prints stub
-hammer recipes --show NAME                # cat the recipe source
-hammer recipes --path NAME                # absolute path
-hammer recipes --edit NAME                # open in $EDITOR (copies gem -> user dir first)
-hammer recipes --run  NAME [ARGS]         # run without installing its bin
-hammer recipes --run  NAME -- --help      # `--` forwards flags to the recipe
+hammer h:recipes                            # list all
+hammer h:recipes --install                  # interactive picker, then prints stub
+hammer h:recipes --show NAME                # cat the recipe source
+hammer h:recipes --path NAME                # absolute path
+hammer h:recipes --edit NAME                # open in $EDITOR (copies gem -> user dir first)
+hammer h:recipes --run  NAME [ARGS]         # run without installing its bin
+hammer h:recipes --run  NAME -- --help      # `--` forwards flags to the recipe
 ```
 
 ## Programmatic use

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

@@ -1,29 +1,37 @@
 class Hammer
-  # Built-in tasks of the `hammer` binary - all live at the root level
-  # (no reserved namespace). Two registration entry points:
-  #
-  # * register_core - tasks always available (subject to user override
-  #   via the `unless commands.key?(...)` guard): :default, :help,
-  #   :update, :agents, :version. These coexist with Hammerfile tasks.
-  #
-  # * register_no_project - tasks meaningful only when no Hammerfile is
-  #   loaded (or `--system` was passed): :recipes, :init. These would
-  #   collide too easily with user tasks if always registered, so the
-  #   Hammerfile branch skips them.
+  # Built-in tasks of the `hammer` binary. Everything but :default lives
+  # under the reserved `h:` namespace (e.g. `hammer h:update`,
+  # `hammer h:recipes`) so the built-ins never collide with a project's
+  # own root tasks. Only the bare `hammer` invocation and the
+  # `-h`/`--help`/`help` request are handled at root - bare fires
+  # :default, which also carries the `--version` convenience flag.
   module Builtins
     module_function
 
-    def register_core(klass)
-      register_help(klass)    unless klass.commands.key?('help')
+    # Single registration entry point - identical in every context
+    # (project Hammerfile or bare `hammer` binary). Namespacing under
+    # `h:` removes the old collision worries, so there's no core vs
+    # no-project split and no hidden-desc dance: the same tasks register
+    # everywhere, always dispatchable, and surface in the listing only
+    # under the extended `--help` view (the `@builtin_namespace` flag).
+    def register(klass)
       register_default(klass) unless klass.commands.key?('default')
-      register_update(klass)  unless klass.commands.key?('update')
-      register_agents(klass)  unless klass.commands.key?('agents')
-      register_version(klass) unless klass.commands.key?('version')
-    end
 
-    def register_no_project(klass)
-      register_recipes(klass) unless klass.commands.key?('recipes')
-      register_init(klass)    unless klass.commands.key?('init')
+      existed = klass.namespaces.key?('h')
+      klass.namespace(:h) {}          # ensure/reopen the reserved subclass
+      h = klass.namespaces['h']
+      # Flag the tree so the compact listing prunes it - the built-ins
+      # only show under the extended `--help` view (always dispatchable).
+      # Skip when the user already owns an `h:` namespace, so their own
+      # tasks stay visible in the bare listing.
+      h.instance_variable_set(:@builtin_namespace, true) unless existed
+      register_help(h)    unless h.commands.key?('help')
+      register_update(h)  unless h.commands.key?('update')
+      register_agents(h)  unless h.commands.key?('agents')
+      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)
@@ -37,9 +45,9 @@ class Hammer
             per-command help; with a namespace prefix prints that
             namespace's command listing.
           TXT
-          example 'help'
-          example 'help build'
-          example 'help db:'
+          example 'h:help'
+          example 'h:help build'
+          example 'h:help db:'
           proc do |opts|
             self.class.root.print_help(opts[:args].first, extended: true)
           end
@@ -105,11 +113,34 @@ 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
     # `--run NAME [ARGS]` - use `--` to forward flags to the recipe
-    # itself (e.g. `hammer recipes --run srt -- --help`).
+    # itself (e.g. `hammer h:recipes --run srt -- --help`).
     def register_recipes(klass)
       klass.class_eval do
         task :recipes do
@@ -123,12 +154,12 @@ class Hammer
           opt :path,    type: :boolean, desc: 'print recipe abs path'
           opt :edit,    type: :boolean, desc: 'open recipe in $EDITOR (copies gem -> user dir first)'
           opt :run,     type: :boolean, desc: 'run a recipe without installing its bin (forwards remaining args)'
-          example 'recipes'
-          example 'recipes --install srt ~/bin/srt    # write + chmod in one shot'
-          example 'recipes --install srt > ~/bin/srt && chmod +x $_'
-          example 'recipes --show srt'
-          example 'recipes --run srt extract movie.mp4'
-          example 'recipes --run srt -- --help        # -- forwards flags to the recipe'
+          example 'h:recipes'
+          example 'h:recipes --install srt ~/bin/srt    # write + chmod in one shot'
+          example 'h:recipes --install srt > ~/bin/srt && chmod +x $_'
+          example 'h:recipes --show srt'
+          example 'h:recipes --run srt extract movie.mp4'
+          example 'h:recipes --run srt -- --help        # -- forwards flags to the recipe'
           proc do |opts|
             args = opts[:args]
             if opts[:install]
@@ -170,7 +201,7 @@ class Hammer
 
       def require_name!(name, action)
         return name if name
-        Shell.print_error "missing recipe name (usage: recipes --#{action} NAME)"
+        Shell.print_error "missing recipe name (usage: h:recipes --#{action} NAME)"
         exit 1
       end
 
@@ -192,7 +223,7 @@ class Hammer
           Shell.say "#{source}:", :yellow
           items.each_key do |name|
             _n, desc, installed = rows.find { |r| r.first == name }
-            status = installed ? "(installed: #{installed})" : "[install: hammer recipes --install #{name}]"
+            status = installed ? "(installed: #{installed})" : "[install: hammer h:recipes --install #{name}]"
             line = "  #{name.ljust(width)}  # #{desc}"
             Shell.say line
             Shell.say "  #{' ' * width}    #{status}", :gray
@@ -242,7 +273,7 @@ class Hammer
       end
 
       # For a gem recipe, offer to copy to user dir first so edits
-      # survive `hammer update`. Then exec $EDITOR on the file.
+      # survive `hammer h:update`. Then exec $EDITOR on the file.
       def edit(name)
         path = Hammer::Recipe.path(name) or fail_unknown(name)
         editor = ENV['EDITOR'] || ENV['VISUAL']

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/dotenv.rb

@@ -38,8 +38,9 @@ class Hammer
         key = key.strip
         next if key.empty?
         val = val.strip
-        if (val.start_with?('"') && val.end_with?('"')) ||
-           (val.start_with?("'") && val.end_with?("'"))
+        if val.length >= 2 &&
+           ((val.start_with?('"') && val.end_with?('"')) ||
+            (val.start_with?("'") && val.end_with?("'")))
           val = val[1..-2]
         end
         out[key] = val

data/lib/hammer/loader.rb

@@ -38,31 +38,37 @@ class Hammer
 
     def resolve_pattern(anchor, pattern)
       abs = File.expand_path(pattern, anchor)
+      # A real file/dir wins over glob interpretation, so a literal path
+      # whose name contains [ ] { } * ? still resolves. Directory: discover
+      # *_hammer.rb under it (empty result is OK - an app may have none).
+      return [abs] if File.file?(abs)
+      return discover(abs) if File.directory?(abs)
       if abs.match?(/[\*\?\[\{]/)
         matches = Dir.glob(abs).sort
         raise Hammer::Error, "load: no files matched #{pattern.inspect}" if matches.empty?
         return matches
       end
-      # Directory: discover *_hammer.rb under it. Empty result is OK
-      # (an app may legitimately have no fragments).
-      return discover(abs) if File.directory?(abs)
-      return [abs] if File.file?(abs)
       raise Hammer::Error, "load: no files matched #{pattern.inspect}"
     end
 
     def discover(dir)
       return [] unless File.directory?(dir)
       out = []
-      walk(dir, out)
+      walk(dir, out, {})
       out.sort
     end
 
-    def walk(dir, out)
+    # `seen` tracks visited real paths so a cyclic directory symlink
+    # doesn't recurse forever.
+    def walk(dir, out, seen)
+      real = File.realpath(dir) rescue dir
+      return if seen[real]
+      seen[real] = true
       Dir.each_child(dir) do |entry|
         full = File.join(dir, entry)
         if File.directory?(full)
           next if SKIP_DIRS.include?(entry) || entry.start_with?('.')
-          walk(full, out)
+          walk(full, out, seen)
         elsif entry.end_with?('_hammer.rb')
           out << full
         end

data/lib/hammer/option.rb

@@ -59,6 +59,8 @@ class Hammer
       when :array   then value.is_a?(Array) ? value : value.to_s.split(',')
       else value.to_s
       end
+    rescue ArgumentError, TypeError
+      raise Hammer::Parser::Error, "invalid #{type} value for --#{name}: #{value.inspect}"
     end
 
     def usage
@@ -76,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