lux-hammer 0.3.17 → 0.3.20

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b3fcc893fd7391f6b7cdd1694fd243729b3319344727a88bcf8599cdd1d23e6d
-  data.tar.gz: f722dd982a954141f551832b8d742ba317d5aff3430611929dd2a261df550545
+  metadata.gz: 0547c6b7b08fe92297694e5d3f19d4726bc3ec3781e9a7169bfeefd1191f7cdd
+  data.tar.gz: e2c8bd882af53a49a24e881ec2329241430c63ec1d6a9f90dd310c4e258364ed
 SHA512:
-  metadata.gz: 43d2baaf2c2451279d8d9ffb1d78209cff145471781858401efa313c274914795ec03aa078be8b1b083d7ed89bf6fe327b8d592c6e4a25ed6744e1d15b382fe7
-  data.tar.gz: 37e28dc827e1492f3ac5efd346edd2bdafac3bd6d53a6e267f8f4a49937813d46ca514ecf9a2bb0f39ec6b52e8b098ee04f4dc58633948c9bf5e042e3512707c
+  metadata.gz: 94bf60197a56713381b1201a8344941595083770c4b3d8d753b624d455326f7cf5208923d49f3046d436bbfe560f28bbfc97bcfe44f5cf4fe85657b856e5f9e8
+  data.tar.gz: 5d5d8d807fd5dee383a528d0e8b38d8a275b4d553ac873c30e703641ed6d85d2f203fbd604384624c25c03f4971b4eb51e3d9c28145a0af06f5067cb189083f9

data/.version

@@ -1 +1 @@
-0.3.17
+0.3.20

data/AGENTS.md

@@ -38,7 +38,8 @@ usable as a library (`require 'lux-hammer'`, subclass `Hammer`, call
 bin/hammer                  # CLI entry point
 lib/lux-hammer.rb           # Entry - defines class Hammer and its DSL
 lib/hammer/shell.rb         # ANSI/IO helpers
-lib/hammer/option.rb        # One option definition
+lib/hammer/option.rb        # One option definition (types: string/boolean/integer/float/array/json)
+lib/hammer/input.rb         # opts[:stdin], prepare_json!, JSON @file / pipe helpers
 lib/hammer/parser.rb        # ARGV -> [positional, opts_hash]
 lib/hammer/command.rb       # One registered command (name, opts, alts, handler)
 lib/hammer/cron.rb          # `cron '<expr>'` schedule parser (cron/interval/@shortcut)
@@ -72,12 +73,19 @@ Inside a `task :name do ... end` block (CommandBuilder context):
   the brief shown in listings, full text renders in per-command help)
 * `example 'invocation example'` (callable many times)
 * `opt :name, type:, default:, alias:, desc:, req:` - any other kwarg
-  raises `Hammer::Error` ("unknown opt parameter(s)")
+  raises `Hammer::Error` ("unknown opt parameter(s)"). Types include
+  `:string`, `:boolean`, `:integer`, `:float`, `:array`, `:json`
+  (`:json` is flag/file/pipe only — never bare positional).
+* `global_opt :name, ...` - same kwargs as `opt`, available on every
+  command under the declaring class/namespace (help: "Global options").
 * `alt :other_name` (callable many times)
 * `needs :other_cmd, 'ns:cmd'` - prereqs run before the handler;
   resolved against root (same lookup as `hammer`), deduped per
   top-level `start` so each prereq fires at most once. Dedupe also
   spans `+`-chained segments. Unknown prereq raises `Hammer::Error`.
+* `opts[:stdin]` is always attached in `run_command` (piped non-TTY
+  body or `nil`). JSON body coercion is opt-in via
+  `Hammer.prepare_json!(opts)` (usually from `before`).
 * `cron '<expr>'` - schedule for the `h:cron` job server. Accepts
   5-field cron (`'*/10 * * * *'`), an interval (`'10s'`, `'10m'`,
   `'2h'`, `'1d'`, counted from the last run) or `@hourly` / `@daily` /
@@ -217,10 +225,12 @@ explicit ADR-level discussion. Keys:
   `> prog cmd --opt=val ARG` banner so it's visible which command was
   actually picked when fuzzy matching kicks in. Only options that
   differ from their default are listed; booleans render as `--flag`
-  / `--no-flag`. Help paths (`-h`, bare namespace) short-circuit
-  before the banner. Set `HAMMER_QUIET=1` to suppress the banner
-  globally - useful when a task writes machine-readable output to
-  stdout (e.g. a JSON-emitting Claude Code / Codex hook).
+  when true (no auto `--no-flag`). Help paths (`-h`, bare namespace)
+  short-circuit before the banner. Set `HAMMER_QUIET=1` to suppress
+  the banner globally - useful when a task writes machine-readable
+  output to stdout (e.g. a JSON-emitting Claude Code / Codex hook).
+  Boolean opts: presence of the switch/alias sets true; there is no
+  auto-negation from a `--no-` prefix.
 * There is **no per-level dispatch**. A namespace is a container, not a
   CLI of its own. Do not reintroduce `subclass.start(remaining_argv)`.
 * `start(argv)` is a two-step pipeline: `split_chain(argv)` (private)

data/README.md

@@ -274,11 +274,14 @@ Not supported: attached short form (`-p3000`), combined short flags
 For boolean options:
 
 ```
---verbose          # set to true
---no-verbose       # set to false (only if a default of true is in play)
+--verbose          # set to true (presence alone)
 -v                 # short alias if declared
+--no-reset         # also true if the opt is named :no_reset
 ```
 
+There is **no** auto `--no-X` negation. Name the flag what you mean
+(`:verbose`, `:no_reset`, `:force`).
+
 ### Per-type behavior
 
 #### `:string` (default)
@@ -295,19 +298,20 @@ hammer build                    # opts[:env] = "dev"  (default)
 #### `:boolean`
 
 ```ruby
-opt :verbose, type: :boolean, alias: :v
-opt :cache,   type: :boolean, default: true
+opt :verbose,  type: :boolean, alias: :v
+opt :no_reset, type: :boolean
+opt :cache,    type: :boolean, default: true
 ```
 ```
-hammer build -v                 # opts[:verbose] = true
-hammer build --verbose          # opts[:verbose] = true
-hammer build --no-cache         # opts[:cache]   = false  (negates default)
-hammer build                    # opts[:cache]   = true   (default)
-                                # opts[:verbose] = nil    (no default)
+hammer build -v                 # opts[:verbose]  = true
+hammer build --verbose          # opts[:verbose]  = true
+hammer build --no-reset         # opts[:no_reset] = true  (name is the flag)
+hammer build                    # opts[:cache]    = true  (default)
+                                # opts[:verbose]  = nil   (no default)
 ```
 
-Booleans never consume a positional. `--no-X` only meaningfully overrides
-a `default: true`.
+Booleans never consume a positional. Presence → true; omitted → default
+(or nil). Use `--flag=false` only if you need an explicit false value.
 
 #### `:integer`
 
@@ -500,6 +504,72 @@ namespace :db do
 end
 ```
 
+## Stdin, JSON input, and global options
+
+Every command receives **`opts[:stdin]`** automatically when stdin is a
+pipe (non-TTY) and non-empty; otherwise it is `nil`. Interactive TTYs are
+never consumed.
+
+```ruby
+task :count do
+  proc { |o| say "bytes=#{o[:stdin]&.bytesize || 0}" }
+end
+# cat file.txt | hammer count
+```
+
+### `type: :json` and `Hammer.prepare_json!`
+
+For JSON bodies, declare `type: :json` and (optionally) coerce in a
+`before` hook so pipes, `@file`, `-`, and inline JSON all land as a
+**Hash/Array** on the same key:
+
+```ruby
+global_opt :json, type: :json, desc: 'JSON body (inline, @file, -, or pipe)'
+before { |o| Hammer.prepare_json!(o) }   # fills o[:json] from stdin when unset
+
+task :create do
+  opt :name
+  proc do |o|
+    body = o[:json] || {}
+    body[:name] ||= o[:name]
+    # body is a Hash with symbol keys
+  end
+end
+```
+
+Supply the body any of these ways (equivalent when `prepare_json!` runs):
+
+```sh
+hammer create --json '{"name":"Ship"}'
+hammer create --json @payload.json
+cat payload.json | hammer create
+cat payload.json | hammer create --json -    # explicit stdin
+```
+
+Rules for `Hammer.prepare_json!(opts, key: :json)`:
+
+1. Already a Hash/Array → leave (symbolize keys).
+2. String → parse inline JSON, `@path`, or `-` (stdin).
+3. `nil` + stdin looks like `{` / `[` → parse stdin into `opts[key]`.
+4. Boolean left alone (legacy `opt :json, type: :boolean` output flags).
+
+`type: :json` **never** takes a bare positional (flag / file / pipe only),
+so it won't steal `REF` from `update REF`.
+
+### `global_opt`
+
+Register options once at root (or a namespace); every command under that
+scope accepts them. Shown under **Global options:** in help. Declared
+**after** per-task opts for positional fill order.
+
+```ruby
+global_opt :json, type: :json
+global_opt :as_json, type: :boolean, alias: :j, default: false,
+           desc: 'Force JSON on stdout'
+```
+
+Helpers: `Hammer.prepare_json!`, `Hammer.attach_stdin!`, `Hammer::Input.*`.
+
 `.env` and `.env.local` next to the `Hammerfile` are loaded
 automatically by the `hammer` binary - no `before` hook needed.
 Shell-set vars are never overwritten, and `.env.local` overrides
@@ -794,10 +864,10 @@ positionals become positional ARGV; kwargs become CLI flags:
 * `hammer 'db:users:list'` → `db:users:list`
 * `hammer :evaluate, 'puts 42'` → `evaluate "puts 42"` (positional ARGV)
 * `verbose: true` → `--verbose`
-* `no_cache: true` → `--no-cache` (underscores in the key become dashes)
+* `no_reset: true` → `--no-reset` (underscores in the key become dashes)
 * `dry_run: true` → `--dry-run`
 * `env: 'prod'` → `--env=prod`
-* `anything: false` → skipped (no-op; use `no_x: true` to negate)
+* `anything: false` → skipped (false flags are omitted)
 
 `MyCli.hammer 'db:users:list', verbose: true` also works at the
 class level, useful for tests and scripting.

data/lib/hammer/builder.rb

@@ -45,6 +45,11 @@ class Hammer
       @klass.before(&block)
     end
 
+    # Options available on every command (see Hammer.global_opt).
+    def global_opt(name, **opts)
+      @klass.global_opt(name, **opts)
+    end
+
     # Opt out of auto `.env` loading in `Hammer.cli`. Default is on.
     def dotenv(flag = true)
       @klass.dotenv(flag)
@@ -75,7 +80,7 @@ class Hammer
   # still call `task`, `namespace`, and `before`. Delegates to whichever
   # Hammer subclass is currently being evaluated.
   module DSL
-    %i[task namespace before dotenv].each do |m|
+    %i[task namespace before dotenv global_opt].each do |m|
       define_method(m) do |*args, &block|
         target = Thread.current[:hammer_target]
         raise Hammer::Error, "`#{m}` called outside a Hammer context " \

data/lib/hammer/input.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+require 'json'
+
+class Hammer
+  # Stdin + JSON helpers for opts. Hammer always attaches piped stdin as
+  # `opts[:stdin]`; recipes opt into JSON body handling via
+  # `Hammer::Input.prepare_json!` (typically from a `before` hook) and/or
+  # `opt :json, type: :json` / `global_opt :json, type: :json`.
+  module Input
+    module_function
+
+    # Read piped stdin once. Returns nil when stdin is a TTY or empty.
+    # Does not consume an interactive TTY.
+    def read_stdin
+      return nil if $stdin.closed?
+      return nil if $stdin.tty?
+
+      data = $stdin.read
+      return nil if data.nil?
+
+      data = data.dup.force_encoding(Encoding::UTF_8) if data.respond_to?(:force_encoding)
+      data.empty? ? nil : data
+    rescue StandardError
+      nil
+    end
+
+    # Idempotent: sets opts[:stdin] if not already present.
+    def attach_stdin!(opts)
+      return opts[:stdin] if opts.key?(:stdin)
+
+      opts[:stdin] = read_stdin
+    end
+
+    # Parse a JSON source string into a Hash/Array with symbol keys.
+    # source is only used in error messages ('stdin', '--json', path, ...).
+    def parse_json(raw, source: 'json')
+      data = JSON.parse(raw)
+      symbolize(data)
+    rescue JSON::ParserError => e
+      raise Hammer::Parser::Error, "invalid JSON (#{source}): #{e.message}"
+    end
+
+    # Resolve a value that may be:
+    #   - Hash / Array  -> returned as-is (symbolized if Hash has string keys)
+    #   - "-"           -> use opts[:stdin]
+    #   - "@path"       -> File.read(path)
+    #   - JSON string   -> parse
+    def resolve_json_value(value, opts = {}, source: 'json')
+      return symbolize(value) if value.is_a?(Hash) || value.is_a?(Array)
+
+      s = value.to_s
+      if s == '-'
+        attach_stdin!(opts)
+        raw = opts[:stdin]
+        raise Hammer::Parser::Error, "no JSON on stdin for #{source}" if raw.nil? || raw.empty?
+
+        return parse_json(raw, source: 'stdin')
+      end
+
+      if s.start_with?('@')
+        path = s[1..]
+        raise Hammer::Parser::Error, "JSON file not found: #{path}" unless File.file?(path)
+
+        return parse_json(File.read(path), source: path)
+      end
+
+      parse_json(s, source: source)
+    end
+
+    # Prepare opts[key] as a Hash/Array when possible.
+    #
+    #   1. If opts[key] is already Hash/Array -> symbolize, done
+    #   2. If opts[key] is a String ("...", @file, -) -> parse
+    #   3. If opts[key] is nil/absent and opts[:stdin] looks like JSON
+    #      object/array -> fill from stdin
+    #   4. Boolean true/false left alone (legacy `opt :json, type: :boolean`)
+    #
+    # Returns the resolved value (or nil). Mutates opts.
+    def prepare_json!(opts, key: :json)
+      attach_stdin!(opts)
+      key = key.to_sym
+      val = opts[key]
+
+      if val.is_a?(Hash) || val.is_a?(Array)
+        opts[key] = symbolize(val)
+        return opts[key]
+      end
+
+      if val.is_a?(String) && !val.empty?
+        opts[key] = resolve_json_value(val, opts, source: "--#{key.to_s.tr('_', '-')}")
+        return opts[key]
+      end
+
+      # Skip booleans (output-mode flags) and other non-nil junk.
+      return val unless val.nil?
+
+      raw = opts[:stdin]
+      return nil if raw.nil? || raw.empty?
+
+      stripped = raw.lstrip
+      return nil unless stripped.start_with?('{', '[')
+
+      opts[key] = parse_json(raw, source: 'stdin')
+      opts[key]
+    end
+
+    def symbolize(obj)
+      case obj
+      when Hash
+        obj.each_with_object({}) do |(k, v), h|
+          h[k.respond_to?(:to_sym) ? k.to_sym : k] = symbolize(v)
+        end
+      when Array
+        obj.map { |v| symbolize(v) }
+      else
+        obj
+      end
+    end
+  end
+end

data/lib/hammer/option.rb

@@ -3,7 +3,7 @@ class Hammer
   class Option
     attr_reader :name, :type, :default, :desc, :aliases, :required, :placeholder
 
-    ALLOWED_KEYS    ||= %i[type default desc alias req placeholder].freeze
+    ALLOWED_KEYS    ||= %i[type default desc alias req placeholder positional].freeze
     RESERVED_FLAGS  ||= %w[-h --help].freeze
 
     def initialize(name, **opts)
@@ -22,6 +22,11 @@ class Hammer
       # Custom usage placeholder, e.g. `placeholder: 't/f'` -> `--log t/f`.
       # Falls back to uppercased name (`--log LOG`) when nil.
       @placeholder = opts[:placeholder]
+      # `positional: false` means "flag form only" - the option never claims a
+      # bare positional. For commands that forward their positionals somewhere
+      # else (`llm wrap --lines 3 -- claude`), the default fill would otherwise
+      # swallow the first one.
+      @positional  = opts.key?(:positional) ? !!opts[:positional] : true
 
       # Reserve -h / --help so every command supports them uniformly.
       if RESERVED_FLAGS.include?(switch)
@@ -47,22 +52,33 @@ class Hammer
       "--#{name.to_s.tr('_', '-')}"
     end
 
-    def negation
-      "--no-#{name.to_s.tr('_', '-')}"
-    end
-
     def cast(value)
       case type
       when :boolean then !!value && value != 'false' && value != '0'
       when :integer then Integer(value)
       when :float   then Float(value)
       when :array   then value.is_a?(Array) ? value : value.to_s.split(',')
+      when :json
+        # Hash/Array pass through. Strings may be inline JSON, @file, or "-"
+        # (stdin resolved later by Hammer::Input.prepare_json!). "@" and
+        # inline JSON are parsed here so opts[:x] is already a Hash in
+        # the handler when the flag is used.
+        return value if value.is_a?(Hash) || value.is_a?(Array)
+        s = value.to_s
+        return s if s == '-' || s.empty?
+        Hammer::Input.resolve_json_value(s, {}, source: switch)
       else value.to_s
       end
     rescue ArgumentError, TypeError
       raise Hammer::Parser::Error, "invalid #{type} value for --#{name}: #{value.inspect}"
     end
 
+    # JSON bodies are flags / stdin / @file — never bare positionals. Anything
+    # declared `positional: false` opts out the same way.
+    def skip_positional_fill?
+      type == :json || !@positional
+    end
+
     def usage
       flag = switch
       flag += " #{placeholder || name.to_s.upcase}" unless boolean?
@@ -81,9 +97,9 @@ class Hammer
 
     # 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.
+    # the data behind `usage`.
     def to_h
-      h = {
+      {
         name:        name.to_s,
         type:        type.to_s,
         default:     default,
@@ -94,8 +110,6 @@ class Hammer
         aliases:     aliases,
         usage:       usage.strip
       }
-      h[:negation] = negation if boolean?
-      h
     end
   end
 end

data/lib/hammer/parser.rb

@@ -5,11 +5,10 @@ class Hammer
     Error ||= Class.new(StandardError)
 
     def initialize(options)
-      @options    = options
-      @by_switch  = {}
+      @options   = options
+      @by_switch = {}
       options.each do |opt|
         register_switch(opt.switch, opt)
-        register_switch(opt.negation, opt) if opt.boolean?
         opt.aliases.each { |a| register_switch(a, opt) }
       end
     end
@@ -31,11 +30,7 @@ class Hammer
         if token.start_with?('--') && token.include?('=')
           key, val = token.split('=', 2)
           opt = lookup!(key)
-          if opt.boolean? && key.start_with?('--no-')
-            values[opt.name] = !opt.cast(val)   # `--no-x=false` -> true
-          else
-            values[opt.name] = opt.cast(val)
-          end
+          values[opt.name] = opt.cast(val)
           i += 1
           next
         end
@@ -43,7 +38,8 @@ class Hammer
         if @by_switch.key?(token)
           opt = @by_switch[token]
           if opt.boolean?
-            values[opt.name] = !token.start_with?('--no-')
+            # Presence alone is enough — the flag is true regardless of name.
+            values[opt.name] = true
             i += 1
           else
             val = argv[i + 1]
@@ -74,12 +70,14 @@ class Hammer
       end
 
       # Fill un-set non-boolean opts from positional args in declaration
-      # order. Booleans always need an explicit flag. Scalars take one
-      # positional each; an :array opt slurps whatever's left, so it's
-      # filled last and never starves a later-declared scalar opt.
+      # order. Booleans always need an explicit flag. type: :json and
+      # `positional: false` are flag-only (skip_positional_fill?). Scalars
+      # take one positional each; an :array opt slurps whatever's left,
+      # so it's filled last
+      # and never starves a later-declared scalar opt.
       array_opt = nil
       @options.each do |opt|
-        next if opt.boolean? || values.key?(opt.name)
+        next if opt.boolean? || opt.skip_positional_fill? || values.key?(opt.name)
         if opt.type == :array
           array_opt = opt
           next
@@ -102,7 +100,7 @@ class Hammer
     private
 
     # Map a flag string to its option, refusing silent shadowing when two
-    # options would claim the same switch/negation/alias.
+    # options would claim the same switch/alias.
     def register_switch(flag, opt)
       if (prev = @by_switch[flag]) && prev != opt
         raise Error, "flag #{flag} claimed by both :#{prev.name} and :#{opt.name}"