lux-hammer 0.2.4 → 0.2.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7007c5628c3466147f7776a2de86832fa8737623ef7d91c8c4dc4a4b3db7e557
-  data.tar.gz: 38d2781742e9cb9d8d12c22b3e8c416fe9f26901a7ef0bed678b206f872a9468
+  metadata.gz: 173d405adff150c31284b295fbcc13b56d73a70d6752509f4954f5a89d5f4df7
+  data.tar.gz: 1439b6d6e44bec16a5571ffaec390d98ea945360862fb4514f55fedf89a575df
 SHA512:
-  metadata.gz: d3dd10a43530fd33c1535ea38086eb3a86ce8d3750e3f79acb765b390b667ab70048bda841e3ab3959effcc1438aa0557e07bfd7f24d727d64a8e963a3ed8b6c
-  data.tar.gz: e976dc67d490f64c44044fab9dcad7e2b5431570eefdada070feb2689daba6fea8af46572ba223a6f801c881917ff522f519d08cf19218bd530ac438f91d4759
+  metadata.gz: 537c36703b561535f96fc6dd5454a2f6e01df6cac7059b8115b9c6ed176875edab529fbe0d530695d4bbc233fadb67964f2485baa8497de324e4a76b33de353b
+  data.tar.gz: 3abb187bb1fe58b03571fdbad1aac1e5a22a2023aeda4b8289ac0508813a85916bbc50a6b07b1988d9d888d3aff50b09658d77b5427704c1061a2c475c9bf151

data/.version

@@ -1 +1 @@
-0.2.4
+0.2.6

data/AGENTS.md

@@ -0,0 +1,294 @@
+# AGENTS.md - lux-hammer
+
+Conventions and constraints for AI agents working on this gem.
+
+## What this gem is
+
+A tiny CLI builder stitched together from three influences:
+namespaces and prereqs from Rake, typed option parsing from Thor, and
+the `task :name do ... end` block DSL from Joshua. Users drop a
+`Hammerfile` in their project, run `hammer`, get a structured CLI. Also
+usable as a library (`require 'lux-hammer'`, subclass `Hammer`, call
+`.start(ARGV)`).
+
+## Hard constraints
+
+* **One root constant**: `Hammer`. Never pollute `Object` or introduce
+  another top-level constant. Sub-types live as `Hammer::Shell`,
+  `Hammer::Option`, `Hammer::Parser`, `Hammer::Command`,
+  `Hammer::Loader`, `Hammer::Builder`, `Hammer::CommandBuilder`. The one
+  exception is `String#color(:name)` (defined in `lib/hammer/shell.rb`)
+  - a tiny convenience for `"hi".color(:cyan)`. Do not add more
+  monkey-patches.
+* **Zero runtime dependencies**. The gem must work with stdlib only. New
+  dependencies require explicit user approval.
+* **Ruby >= 2.7**. Do not use language features introduced after 2.7
+  without flagging.
+* **`desc` is single-arg, multi-line allowed**. The argument is one
+  string; it may contain newlines. The first line is the brief shown in
+  command listings, the full string renders (indented) in per-command
+  help. Trailing whitespace is stripped so heredocs work cleanly. `desc`
+  is never multi-arg - that form was tried and reverted.
+* **The `proc` is the trailing expression of a `task` block.** Do not
+  introduce `run do ... end` or similar - the user explicitly chose this.
+
+## File layout
+
+```
+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/parser.rb        # ARGV -> [positional, opts_hash]
+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
+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
+test/option_test.rb         # Option declaration / casting
+test/command_test.rb        # Command data type
+test/shell_test.rb          # ANSI / IO helpers
+test/cli_test.rb            # `hammer` binary end-to-end
+examples/Hammerfile         # Reference Hammerfile
+examples/class_dsl.rb       # Reference class DSL usage
+examples/block_dsl.rb       # Reference block DSL usage
+```
+
+## DSL surface (do not break compatibility silently)
+
+Inside a `task :name do ... end` block (CommandBuilder context):
+
+* `desc 'short description'` (string may contain `\n`; first line is
+  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)")
+* `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`.
+* `proc do |opts| ... end` - **the last expression**, becomes handler
+
+At class scope (for `def`-style commands):
+
+* `desc`, `example`, `opt`, `alt`, `needs` set pending state
+* The next `def` consumes the pending state IF `desc` was set; otherwise
+  the method is treated as a plain helper
+* Methods with arity 0 are called without opts; methods that take an arg
+  receive the opts hash
+
+At class or `Hammerfile` scope:
+
+* `task :name do ... end`
+* `namespace :name do ... end`
+* `load` / `load auto: true` / `load 'path/file.rb'` / `load 'glob/*.rb'` /
+  `load 'some/dir'` - pull in Hammerfile fragments from `*_hammer.rb`
+  files. Paths resolve relative to the caller's file. A directory
+  argument triggers the same recursive scan as `load auto: true` but
+  anchored at the given dir (empty result is OK, no error - apps with
+  no fragments are normal). Globs and explicit file paths still raise
+  on zero matches as a typo guard. Fragments are de-duplicated per
+  target class, so re-entrant `load` is safe. Skipped dirs:
+  `.git`, `.bundle`, `node_modules`, `tmp`, `vendor`, `dist`, `build`,
+  `coverage`, plus any hidden dir. Fragment shape is the block DSL
+  (`task`, `namespace`); class-DSL fragments belong in plain `.rb`
+  files loaded with `require_relative`.
+
+Runtime cross-invocation:
+
+* `hammer(name, *args, **opts)` - `name` is a symbol for a top-level
+  command (`hammer :build`) or a colon-path string for namespaced ones
+  (`hammer 'db:users:list'`). Trailing positionals become positional
+  ARGV. Kwargs become flags: underscores in keys map to dashes,
+  `true` -> `--flag`, `false` -> skipped (use `no_x: true` to negate),
+  any other value -> `--key=value`. Available both on a class
+  (`MyCli.hammer ...`) and inside a handler proc.
+
+## Entry points
+
+* `Hammer.run(argv = ARGV) { ... }` - inline block DSL, builds an
+  anonymous subclass, dispatches `argv` against it.
+* `Hammer.run(argv = ARGV)` - **without a block**: load `./Hammerfile`
+  if present, otherwise auto-discover `*_hammer.rb` under `Dir.pwd`,
+  then dispatch. No walk-up, no chdir. The "do the obvious thing"
+  entry point for a fixed bin script; users who need
+  walk-up + chdir + missing-Hammerfile error use `Hammer.cli`
+  (`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.
+* `class MyCli < Hammer; ... end; MyCli.start(ARGV)` - classic class
+  DSL. `.start` is the dispatch primitive everything else funnels into.
+
+## `opts` hash contract
+
+Always a `Hash` with **symbol keys**. Never change this without an
+explicit ADR-level discussion. Keys:
+
+* one per declared option
+* `opts[:args]` - leftover positional ARGV (after declaration-order
+  fill)
+
+## Dispatch model
+
+* Commands are addressed by colon path: `db:users:list`.
+* The root `Hammer` subclass holds `@commands` and `@namespaces`.
+* `resolve('a:b:c')` walks `@namespaces['a'].namespaces['b']` and
+  finds command `c` in the last class.
+* 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)
+  splits on bare `+` tokens and unescapes `++` -> `+`, then `dispatch`
+  (private) runs each segment. `start` is the only public entry that
+  also sets up the per-invocation `needs`/`before` dedupe state, so the
+  whole `+` chain shares one dedupe scope. Don't have `dispatch` call
+  back into `start` for sub-segments - that re-triggers chain detection
+  on already-unescaped `+` tokens (bug we fixed; the test
+  `test_chain_escape_double_plus_yields_literal_plus_arg` guards it).
+
+## Help formatting
+
+* Program name in usage lines is computed automatically (invocation path
+  relative to cwd if the bin lives inside cwd, otherwise the basename of
+  `$PROGRAM_NAME`). There is no user-facing override; the auto-detection
+  is the whole API. `Hammer.cli` warms the cache before chdir-ing into
+  the Hammerfile's directory so the resolved name stays relative to the
+  cwd the user invoked from.
+* `hammer` (no args), `hammer -h`, and `hammer --help` all print top-level help.
+* `hammer COMMAND -h` / `--help` prints per-command help (reserved on every command).
+* Commands listed flat with colon paths, grouped by top-level namespace.
+* Bare namespace (`hammer db`) prints the same listing scoped to that
+  namespace.
+* Per-command help: usage line shows declared opts inline (required
+  bare, optional bracketed), then options with `(default: ...)` /
+  `(required)` annotations, then examples.
+
+## Inline helpers (`Hammer::Shell`)
+
+Mixed into every handler. Also callable directly as `Hammer::Shell.<x>`.
+Complete surface:
+
+```ruby
+say 'plain'                          # print
+say.green 'ok'                       # colored via proxy (preferred form)
+say 'ok', :green                     # equivalent two-arg form
+say ''                               # blank line (NOT `say` with no args)
+
+'OK'.color(:green)                   # paint without printing
+Hammer::Shell.paint('x', :red)       # the underlying primitive
+
+error 'config missing' unless ok     # raise Hammer::Error -> dispatcher exits 1
+name = ask 'name'                    # read line
+env  = ask 'env', default: 'dev'     # blank input -> default
+exit 0 unless yes? 'continue?'       # y/Y prefix -> true, else false
+idx = choose 'Pick env', envs        # arrow-key picker, returns Integer or nil
+sh 'bundle install'                  # echo "$ cmd" gray, raise on non-zero
+
+Hammer::Shell.color!(true|false)     # force ANSI on/off
+Hammer::Shell.color?                 # current state
+Hammer::Shell.print_error 'msg'      # stderr, no raise - dispatcher-only
+```
+
+Doc rule: prefer `say.<color> 'x'` over `say 'x', :<color>` in README
+and examples - both work, but the proxy form reads better and is what
+new code in this gem should show.
+
+`choose` invariants worth knowing:
+
+* Uses `io/console` (stdlib, no new dependency).
+* TTY path renders the list, redraws on each keystroke (`\e[NA\e[J`),
+  hides/restores the cursor, and reads bytes via `$stdin.raw { ... }`.
+* Keys: `j`/`k` and arrow keys (ESC `[` `A`/`B`) move; Enter confirms;
+  `q`, ESC alone, and Ctrl-C cancel. ESC-vs-arrow is disambiguated with
+  a tiny `IO.select` timeout - the arrow's `[A` follows ESC immediately,
+  a bare ESC keystroke is alone.
+* Non-TTY path (`!$stdin.tty?` or stdin without `raw`) prints a numbered
+  list and reads one line. Both paths return the same: `Integer` index
+  or `nil`. Don't break this contract - it's why `choose` is scriptable.
+* On confirm, the rendered list is collapsed to one green line; on
+  cancel, the list is cleared. Don't leave the raw-mode list behind.
+* Empty `items` raises `Hammer::Error` ('at least one item') - same
+  failure pattern as bad colors.
+
+## Colors
+
+* Color set: `:black :red :green :yellow :blue :magenta :cyan :white :gray`
+  (see `Hammer::Shell::COLORS`). No bold, no bright variants, no
+  background colors. Don't add more without an explicit ask.
+* All four entry points (`say x, :c`, `say.c x`, `paint x, :c`,
+  `'x'.color(:c)`) flow through `Shell.paint` - it's the only place
+  ANSI codes live.
+* Unknown colors must raise `Hammer::Error` with the list of valid
+  names. This is enforced in `Shell.paint` and in `SayProxy#method_missing`
+  - don't bypass it. Validation runs even when colors are disabled, so
+  a typo fails loudly in CI.
+* `say` with no args returns the `SayProxy`; `say ''` is how you print
+  a blank line. Don't restore `say` (no args) -> blank-line semantics.
+
+## Error handling
+
+* `Hammer::Shell.error 'msg'` raises `Hammer::Error`. The dispatcher
+  catches it inside `run_command`, prints `[error] msg` in red to
+  stderr, and exits 1 - no backtrace, no per-command help.
+* `Hammer::Shell.print_error 'msg'` prints without raising; reserved
+  for the dispatcher's own diagnostics (unknown command, missing
+  Hammerfile).
+* `Hammer::Parser::Error` is also caught in `run_command` and
+  additionally prints per-command help (because the input *was* aimed
+  at that command).
+* Inside a handler, just call `error 'msg'` - it resolves via the
+  `Shell` mixin.
+
+## Coding rules
+
+* No trailing spaces on empty lines. End every file with a newline.
+* Use ASCII only - `-`, not unicode dashes; `*` for bullets in docs.
+* Preserve existing style. Minimize diff size.
+* Comments only when the *why* is non-obvious. Don't restate the code.
+* No `// removed` markers - delete cleanly.
+* Constants: prefer `FOO ||=` over `FOO =` (re-load safety).
+* Never commit or push without explicit confirmation.
+
+## Testing
+
+* Run: `bundle exec rake test`
+* Single file: `bundle exec ruby -Ilib -Itest test/parser_test.rb`
+* Single test by name: `... test/parser_test.rb -n test_boolean_via_short_alias`
+* Helper `CaptureIO` in `test/test_helper.rb` swaps `$stdout`/`$stderr`
+  for `StringIO`. Use `capture { ... }` for non-exiting code and
+  `capture_exit { ... }` for code that calls `exit`.
+
+When you add a feature, add a test in the matching `_test.rb`. When you
+fix a bug, write the failing test first.
+
+## What NOT to do
+
+* Don't add generators / templates (Thor-style file scaffolding).
+* Don't add shell-completion generation to core - that belongs in a
+  separate plugin gem.
+* Don't introduce a class hierarchy for commands. Commands are data
+  (`Hammer::Command` instances), not classes.
+* Don't reintroduce a user-facing `program` / `program_name` setter -
+  the auto-detected name is the whole API and was deliberately reduced
+  to that.
+* Don't propagate `program_name` into namespaces as a longer prefix -
+  there is only one program name.
+* Don't make `desc` multi-arg again (it once took `usage, description`
+  - that was reverted intentionally).
+* Don't add a `subcommand 'name', SomeClass` form - it was replaced by
+  `namespace :name do ... end` intentionally.
+* Don't auto-namespace fragments by filename (e.g. `db_hammer.rb` does
+  not implicitly wrap in `namespace :db do ... end`). Be explicit, as
+  Rake's `import` is. If a fragment wants a namespace, it writes it.
+
+## When in doubt
+
+* Read `lib/lux-hammer.rb` top-to-bottom. It's the whole DSL surface.
+* Run the example: `cd examples && ruby -I../lib ../bin/hammer`
+* Check `test/dsl_test.rb` for the canonical behavior of each feature.
+* Check `test/load_test.rb` for `load` / fragment loader behavior.

data/README.md

@@ -1,16 +1,17 @@
 # hammer
 
-The bastard Frankenstein child of Rake, Thor, and Joshua. Sewn
-together from three good ideas, with the rest of each parent left on
+The bastard Frankenstein child of Rake](https://github.com/ruby/rake),
+[Thor](https://github.com/rails/thor), and [Joshua](https://github.com/dux/joshua).
+Sewn together from three good ideas, with the rest of each parent left on
 the cutting room floor.
 
 Drop a `Hammerfile`, run `hammer`, ship. AI LLM-s love `hammer`.
 
 ```ruby
-namespace :db do                          # Rake-style colon paths
-  task :migrate do                      # Joshua-style task block
+namespace :db do                            # Rake-style colon paths
+  task :migrate do                          # Joshua-style task block
     desc 'Run pending migrations'
-    opt :pretend, type: :boolean, alias: :p   # Thor-style typed opts
+    opt :pretend, type: :boolean, alias: :p # Thor-style typed opts
     proc do |o|
       say.green "migrating pretend=#{o[:pretend].inspect}"
     end

data/bin/hammer

@@ -1,9 +1,10 @@
 #!/usr/bin/env ruby
-begin
-  require 'lux-hammer'
-rescue LoadError
-  # dev fallback: running from the repo without the gem installed
-  $LOAD_PATH.unshift File.expand_path('../lib', __dir__)
-  require 'lux-hammer'
+# Prefer the adjacent lib/ when this script lives in a repo checkout
+# (lib/lux-hammer.rb sits next to bin/), otherwise fall back to the
+# installed gem. Otherwise an installed older gem shadows local edits.
+local_lib = File.expand_path('../lib/lux-hammer.rb', __dir__)
+if File.file?(local_lib)
+  $LOAD_PATH.unshift File.dirname(local_lib)
 end
+require 'lux-hammer'
 Hammer.cli(ARGV)

data/lib/lux-hammer.rb

@@ -467,6 +467,7 @@ class Hammer
         Shell.say ''
         print_command_list(self)
       end
+      print_global_flags
       print_footer
     end
 
@@ -478,6 +479,7 @@ class Hammer
         Shell.say ''
         print_command_list(ns, prefix)
       end
+      print_global_flags
       print_footer
     end
 
@@ -490,6 +492,16 @@ class Hammer
 
     HOMEPAGE ||= 'https://github.com/dux/hammer'.freeze
 
+    # Global flags only exist when invoked via the `hammer` binary
+    # (see `Hammer.cli`), not for user-built CLIs that call `start`
+    # on their own subclass.
+    def print_global_flags
+      return unless root.instance_variable_get(:@hammer_binary)
+      Shell.say ''
+      Shell.say 'Global:', :yellow
+      Shell.say '  --ai  # Print AGENTS.md (AI-friendly Hammerfile authoring docs)'
+    end
+
     def print_footer
       Shell.say ''
       Shell.say "powered by hammer - #{HOMEPAGE}", :gray
@@ -505,13 +517,13 @@ class Hammer
 
       # 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) }
-      width  = rows.map { |full, c| label_for(full, c).length }.max
+      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 }, width)
+        emit_rows(rooted.sort_by { |full, _| [full.count(':'), full] }, width)
         first = false
       end
 
@@ -519,14 +531,14 @@ class Hammer
         Shell.say unless first
         first = false
         Shell.say "#{section}:", :yellow
-        emit_rows(items.sort_by { |full, _| full }, width)
+        emit_rows(items.sort_by { |full, _| [full.count(':'), full] }, width)
       end
     end
 
     def emit_rows(rows, width)
       rows.each do |full, c|
-        label = label_for(full, c)
-        Shell.say "  #{program_name} #{label.ljust(width)}  # #{c.brief}"
+        brief = c.alts.empty? ? c.brief : "#{c.brief} (alt: #{c.alts.join(', ')})"
+        Shell.say "  #{program_name} #{full.ljust(width)}  # #{brief}"
       end
     end
 
@@ -534,17 +546,18 @@ class Hammer
     # for 'db:users:list' viewed from 'db'; :root if the command sits at
     # the view's top level. Only the first segment under the view groups,
     # so deeper paths fold into their top-level section.
-    def section_for(full, prefix)
-      segs = full.split(':')[0..-2]
-      if prefix && !prefix.empty?
-        segs = segs[prefix.split(':').size..] || []
+    #
+    # Exception: a bare command that shares its name with a sibling
+    # namespace (e.g. `mount` alongside a `mount:` namespace) groups
+    # under that namespace's section, not :root.
+    def section_for(full, prefix, klass = nil)
+      segs = full.split(':')
+      segs = segs[prefix.split(':').size..] || [] if prefix && !prefix.empty?
+      if segs.size == 1 && klass && klass.namespaces.key?(segs.first)
+        return segs.first
       end
-      segs.empty? ? :root : segs.first
-    end
-
-    # "db:migrate" or "db:migrate (alt: m)"
-    def label_for(full, cmd)
-      cmd.alts.empty? ? full : "#{full} (alt: #{cmd.alts.join(', ')})"
+      parent = segs[0..-2]
+      parent.empty? ? :root : parent.first
     end
 
     # " URL [ENV] [OPTIONS]" - shows the positional-fill names for
@@ -619,10 +632,31 @@ class Hammer
     klass.start(argv)
   end
 
+  # Dump the gem's AGENTS.md to stdout - AI-optimized guide for
+  # writing Hammerfiles. Bundled with the gem and resolved relative
+  # to this file so it works from any install location.
+  def self.print_ai_help
+    path = File.expand_path('../AGENTS.md', __dir__)
+    if File.file?(path)
+      puts File.read(path)
+    else
+      Shell.print_error "AGENTS.md not found at #{path}"
+      exit 1
+    end
+  end
+
   # Entry point for the `hammer` binary. Walks up from CWD until it
   # finds a Hammerfile, evaluates it as the block DSL, then dispatches
   # ARGV against the resulting CLI.
+  #
+  # `--ai` is a meta-flag handled here, before Hammerfile lookup,
+  # so it works anywhere (no project required).
   def self.cli(argv = ARGV)
+    if argv.include?('--ai')
+      print_ai_help
+      exit 0
+    end
+
     path = find_hammerfile(Dir.pwd)
     unless path
       Shell.print_error "no Hammerfile found in #{Dir.pwd} or any parent directory"
@@ -649,10 +683,15 @@ class Hammer
           end
         end
       RUBY
+      Shell.say ''
+      Shell.say "tip: run `#{File.basename($PROGRAM_NAME)} --ai` for AI-friendly Hammerfile authoring docs", :gray
       exit 1
     end
 
     klass = Class.new(Hammer)
+    # Mark this class as the `hammer` binary's root so help output can
+    # surface binary-only globals like `--ai`.
+    klass.instance_variable_set(:@hammer_binary, true)
     # Resolve before chdir so paths like `bin/foo` stay relative to the
     # cwd the user actually invoked from. `program_name` memoizes.
     klass.program_name

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: lux-hammer
 version: !ruby/object:Gem::Version
-  version: 0.2.4
+  version: 0.2.6
 platform: ruby
 authors:
 - Dino Reic
@@ -32,6 +32,7 @@ extensions: []
 extra_rdoc_files: []
 files:
 - "./.version"
+- "./AGENTS.md"
 - "./README.md"
 - "./bin/hammer"
 - "./lib/hammer/builder.rb"