lux-hammer 0.2.3 → 0.2.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ae2c5c9dbcd3b17941440e327e04e84dbffaec7209e4ce15b205cf83525b3724
-  data.tar.gz: 516eb4a4cb0f8f02f489eb00d2e4500cfe70f600eaebe192fb1749c81fe37074
+  metadata.gz: bb668fabef5892decb2ee58add685f52dad7fe742ae0cd8597ba62da576c3d13
+  data.tar.gz: f74beef4ccb0af5aaa546c7c4a2dec29bc08fffdb929edfa5f3dcdf261627b69
 SHA512:
-  metadata.gz: d922e58738cb3afc95c54864fc79d9a6ec556e3634a94f258711652abf220ba7f436e1d0f0cf24f48ba9c6372af22339d8377b491c9de93f708e19a7ca13692d
-  data.tar.gz: 6ad385997b87bf70ba58ec3ae6d701b3717d5e9584ef00aae29ebeb5c9b3666a39f6032277e275987f6de94161809767eeb838e288718fda09287327009756b6
+  metadata.gz: 9fddfa7b7f657cb1baa30793e46fe331cd3f65704ac31ce582bcfc851b154a15eb72e5610e0a0b8af29ed99a763823f7c7bbdd1ef7ad33f40b95fcd803a6216f
+  data.tar.gz: 6b176bb61def54c305a28f0c9b9419074ed16c14c1b8412ccc084cd2ed5f1a0bfa93d947aac9fcce704cde00c2307bb897e0255e200f1bf1bb077f2795f40330

data/.version

@@ -1 +1 @@
-0.2.3
+0.2.5

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

@@ -4,11 +4,11 @@ The bastard Frankenstein child of Rake, Thor, and 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.
+Drop a `Hammerfile`, run `hammer`, ship. AI LLM-s love `hammer`.
 
 ```ruby
 namespace :db do                          # Rake-style colon paths
-  define :migrate do                      # Joshua-style define block
+  task :migrate do                      # Joshua-style task block
     desc 'Run pending migrations'
     opt :pretend, type: :boolean, alias: :p   # Thor-style typed opts
     proc do |o|
@@ -40,7 +40,7 @@ migrating pretend=true
   that most CLIs never reach for.
 
 * **From [Joshua](https://github.com/dux/joshua)** we took the
-  *`define :name do ... end` block DSL* - declarative metadata up
+  *`task :name do ... end` block DSL* - declarative metadata up
   top, one `proc do |opts| ... end` at the bottom doing the work. No
   `def`-and-`desc` split, no class required, no boilerplate between
   "what this command is" and "what it does".
@@ -67,7 +67,7 @@ This installs the `hammer` binary and exposes `require 'lux-hammer'`.
 Create a `Hammerfile` in your project root:
 
 ```ruby
-define :hello do
+task :hello do
   desc 'say hi'
   proc do |opts|
     say.green "hello #{opts[:args].first || 'world'}"
@@ -115,7 +115,7 @@ Hammer takes typed options, positional fill, and any common flag form:
 
 ```ruby
 # Hammerfile
-define :greet do
+task :greet do
   desc 'Say hello'
   opt :name
   opt :loud, type: :boolean, alias: :l
@@ -159,7 +159,7 @@ end
 
 ```ruby
 # hammer - one arg system, real aliases, no usage string to maintain
-define :greet do
+task :greet do
   desc 'Say hello'
   alt :g
   opt :name
@@ -173,13 +173,13 @@ and there's one place to look for everything the command takes.
 
 ## The two styles
 
-### `define :name do ... end` (block DSL)
+### `task :name do ... end` (block DSL)
 
 The block's **last expression must be `proc do |opts| ... end`**. That
 proc is the handler. Everything before it is metadata.
 
 ```ruby
-define :build do
+task :build do
   desc    'Build the project'
   example 'build prod -v'
   opt :verbose, type: :boolean, alias: :v
@@ -371,7 +371,7 @@ Anything in ARGV without `-` / `--` fills the next un-set
 **non-boolean** opt, in declaration order:
 
 ```ruby
-define :deploy do
+task :deploy do
   opt :url
   opt :env, default: 'dev'
   proc { |opts| ... }
@@ -403,7 +403,7 @@ Always a `Hash` with **symbol keys**. Keys present:
 * `opts[:args]` - array of positional ARGV not absorbed by an opt
 
 ```ruby
-define :show do
+task :show do
   opt :env, default: 'dev'
   opt :loud, type: :boolean
   proc { |opts| p opts }
@@ -435,12 +435,12 @@ colon-paths from the root binary - just like `rake db:migrate`:
 
 ```ruby
 namespace :db do
-  define :migrate do
+  task :migrate do
     proc { |opts| ... }
   end
 
   namespace :users do
-    define :list do
+    task :list do
       proc { |opts| ... }
     end
   end
@@ -453,7 +453,9 @@ Then:
 hammer db:migrate
 hammer db:users:list
 hammer db                 # bare namespace lists everything under it
+hammer db:                # trailing colon: full per-task help for every command
 hammer db:migrate -h      # per-command help
+hammer :                  # trailing colon at root: full help for every command
 ```
 
 Namespaces nest to any depth. There is no per-level dispatch - the root
@@ -470,13 +472,13 @@ before { Dotenv.load }                  # runs before every command
 
 namespace :db do
   before { hammer :env }                # runs before every db:* command
-  define :migrate do
+  task :migrate do
     proc { |opts| ... }                 # no boilerplate require inside
   end
 end
 ```
 
-`before` is intentionally not available inside `define` - the proc body
+`before` is intentionally not available inside `task` - the proc body
 *is* the command body, just put the setup line at the top of the proc.
 
 Pairs naturally with hidden commands (next section): keep `:env` /
@@ -488,13 +490,13 @@ A command declared without a `desc` is **hidden from help listings**
 but stays fully dispatchable and `hammer`-callable:
 
 ```ruby
-define :env do
+task :env do
   proc { |_| require './config/env' }   # no desc -> hidden
 end
 
 namespace :db do
   before { hammer :env }                # call it from a hook
-  define :migrate do
+  task :migrate do
     desc 'Run migrations'
     proc { |_| ... }
   end
@@ -509,17 +511,17 @@ end
 Declare commands that must run before this one (Rake-style task deps):
 
 ```ruby
-define :env do
+task :env do
   proc { |_| require './config/env' }     # hidden helper
 end
 
-define :app do
+task :app do
   needs :env                              # runs `env` first
   desc 'start the app'
   proc { |opts| App.start }
 end
 
-define :deploy do
+task :deploy do
   needs :env, :build                      # multiple prereqs, in order
   proc { |opts| ... }
 end
@@ -542,7 +544,7 @@ only once. Prereqs run with default options (no argv passed through).
 `alt :short_name` (or several) registers extra names for a command:
 
 ```ruby
-define :server do
+task :server do
   alt :s, :srv
   proc { |opts| ... }
 end
@@ -558,7 +560,7 @@ From inside any command's proc - or from outside via the class - you can
 invoke other commands without re-shelling out:
 
 ```ruby
-define :deploy do
+task :deploy do
   proc do |opts|
     hammer :build, env: 'prod', verbose: true
     hammer 'db:migrate'
@@ -729,7 +731,7 @@ load auto: true              # recursive scan for *_hammer.rb from here
 ```ruby
 # tasks/db_hammer.rb
 namespace :db do
-  define :migrate do
+  task :migrate do
     desc 'Run pending migrations'
     opt :pretend, type: :boolean, alias: :p
     proc { |o| say.green "migrating pretend=#{o[:pretend].inspect}" }
@@ -739,7 +741,7 @@ end
 
 ```ruby
 # tasks/deploy_hammer.rb
-define :deploy do
+task :deploy do
   desc 'Deploy to prod'
   proc do |_|
     hammer 'db:migrate'      # cross-file invocation just works
@@ -777,7 +779,7 @@ hidden directory.
 ### Fragment shape
 
 A `*_hammer.rb` file is a **block-DSL fragment** - same surface as a
-`Hammerfile`: `define`, `namespace`, and nested `load`. Not a class
+`Hammerfile`: `task`, `namespace`, and nested `load`. Not a class
 re-open. If you want to extend a `Hammer` subclass in the classic
 `desc` + `def` style across files, use plain `require_relative`.
 
@@ -801,7 +803,7 @@ Same shape as a Hammerfile, just inline:
 require 'lux-hammer'
 
 Hammer.run(ARGV) do
-  define :hello do
+  task :hello do
     desc 'say hi'
     opt :loud, type: :boolean, alias: :l
     proc do |opts|
@@ -845,7 +847,7 @@ end
 
 ```ruby
 # Simple top-level command
-define :build do
+task :build do
   desc    'Build the project'
   example 'build prod -v'
   example 'build --env=staging'
@@ -860,7 +862,7 @@ define :build do
 end
 
 # Command that calls another command
-define :deploy do
+task :deploy do
   desc 'Deploy to URL'
   alt :ship
   opt :url, req: true
@@ -875,7 +877,7 @@ end
 
 # Namespace with two levels of nesting
 namespace :db do
-  define :migrate do
+  task :migrate do
     desc 'Run pending migrations'
     alt :m
     example 'db:migrate 3 --pretend'
@@ -888,7 +890,7 @@ namespace :db do
   end
 
   namespace :users do
-    define :list do
+    task :list do
       desc 'List users'
       opt :role, default: 'all'
       opt :limit, type: :integer, default: 100
@@ -898,7 +900,7 @@ namespace :db do
       end
     end
 
-    define :create do
+    task :create do
       desc 'Create a user'
       opt :email, req: true
       opt :admin, type: :boolean
@@ -968,7 +970,7 @@ directly. Useful for embedding or testing:
 require 'lux-hammer'
 
 class MyCli < Hammer
-  define :greet do
+  task :greet do
     opt :loud, type: :boolean
     proc do |opts|
       msg = "hello #{opts[:args].first}"
@@ -1006,7 +1008,7 @@ few small things that have been bugging me about both for years.
 | Lines of code | ~6,000 | ~400 |
 | Runtime deps | a few | zero |
 | Root constants | `Thor`, `Thor::Group`, `Thor::Shell`, `Thor::Actions`, ... | just `Hammer` |
-| Command DSL | `desc 'usage', 'help'` + `method_option` + `def name(arg)` | `define :name do ... proc do \|opts\| end end` (or classic `desc` + `def`) |
+| Command DSL | `desc 'usage', 'help'` + `method_option` + `def name(arg)` | `task :name do ... proc do \|opts\| end end` (or classic `desc` + `def`) |
 | Opts container | `Thor::CoreExt::HashWithIndifferentAccess` | plain `Hash` with symbol keys |
 | Positional args | method positional params + `method_option`, two parallel systems | declared-order opts fill from positional, single system |
 | Sub-namespaces | `register SubClass, 'name', '...'` (inheritance ceremony) | `namespace :name do ... end` (no classes needed) |

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/hammer/builder.rb

@@ -7,8 +7,8 @@ class Hammer
       @klass = klass
     end
 
-    def define(name, &block)
-      @klass.define(name, &block)
+    def task(name, &block)
+      @klass.task(name, &block)
     end
 
     def namespace(name, &block)

data/lib/hammer/command_builder.rb

@@ -1,5 +1,5 @@
 class Hammer
-  # Context object for `define :name do ... end` blocks. Exposes
+  # Context object for `task :name do ... end` blocks. Exposes
   # desc/example/opt/alt; the block's return value (a `proc do |opts|`)
   # becomes the command handler.
   class CommandBuilder

data/lib/lux-hammer.rb

@@ -11,7 +11,7 @@ require_relative 'hammer/command_builder'
 # Class DSL:
 #
 #   class MyCli < Hammer
-#     define :build do
+#     task :build do
 #       desc    'Build the project'
 #       example 'build -v --env=prod'
 #       opt :verbose, type: :boolean, alias: :v
@@ -27,7 +27,7 @@ require_relative 'hammer/command_builder'
 # Block DSL is identical, just inside `Hammer.run`:
 #
 #   Hammer.run(ARGV) do
-#     define :hello do
+#     task :hello do
 #       desc 'Greet someone'
 #       opt :loud, type: :boolean, alias: :l
 #       proc do |opts|
@@ -124,17 +124,17 @@ class Hammer
     # return a Proc as its last expression. That proc is the handler and
     # receives a single `opts` hash with symbol keys; positional ARGV
     # lives at `opts[:args]`.
-    def define(name, &block)
+    def task(name, &block)
       cmd = Command.new(name: name.to_s)
       handler = CommandBuilder.new(cmd).instance_eval(&block)
       unless handler.is_a?(Proc)
         raise Error, <<~MSG
-          define(:#{name}) block must end with a `proc do |opts| ... end`.
+          task(:#{name}) block must end with a `proc do |opts| ... end`.
           The proc's return value is what becomes the command handler.
 
           Example:
 
-            define :#{name} do
+            task :#{name} do
               desc    'what it does'
               example '#{name} foo --env=prod'
               opt :env, default: 'dev'
@@ -148,7 +148,7 @@ class Hammer
       cmd.handler = handler
       commands[cmd.name] = cmd
 
-      # `define` ignores pending class-level state, but clear it so a
+      # `task` ignores pending class-level state, but clear it so a
       # later `def` doesn't accidentally consume stale metadata.
       @pending_desc = nil
       @pending_examples = []
@@ -158,11 +158,11 @@ class Hammer
     end
 
     # Open a namespace (group of commands). Everything inside the block
-    # (define, nested namespace, ...) belongs to that namespace, evaluated
+    # (task, nested namespace, ...) belongs to that namespace, evaluated
     # against an anonymous Hammer subclass.
     #
     #   namespace :db do
-    #     define :migrate do ... end
+    #     task :migrate do ... end
     #     namespace :users do ... end
     #   end
     def namespace(name, &block)
@@ -189,7 +189,7 @@ class Hammer
     #   before { |opts| Dotenv.load }
     #   namespace :db do
     #     before { hammer :env }
-    #     define :migrate do ... end
+    #     task :migrate do ... end
     #   end
     def before(&block)
       before_hooks << block
@@ -300,6 +300,19 @@ class Hammer
         return print_help(target)
       end
 
+      # Trailing colon ("db:") -> expanded namespace listing with full
+      # per-command help on every task. Bare ":" expands the root.
+      if name.end_with?(':') && name != ':'
+        bare = name.chomp(':')
+        ns = resolve_namespace(bare)
+        return print_namespace_help(bare, ns, full: true) if ns
+        Shell.print_error("unknown namespace: #{bare}")
+        print_help
+        exit 1
+      elsif name == ':'
+        return print_help(nil, full: true)
+      end
+
       cmd, owner = resolve(name)
       return owner.run_command(cmd, argv, full: name) if cmd
 
@@ -429,29 +442,52 @@ class Hammer
       scan.include?('-h') || scan.include?('--help')
     end
 
-    def print_help(target = nil)
+    def print_help(target = nil, full: false)
       if target
+        # `help ns:` is equivalent to `ns:` - expanded namespace listing.
+        if target.end_with?(':') && target != ':'
+          bare = target.chomp(':')
+          ns = resolve_namespace(bare)
+          return print_namespace_help(bare, ns, full: true) if ns
+          Shell.print_error("unknown: #{target}")
+          return
+        end
         cmd, _ = resolve(target)
         return print_command_help(cmd, target) if cmd
         ns = resolve_namespace(target)
-        return print_namespace_help(target, ns) if ns
+        return print_namespace_help(target, ns, full: full) if ns
         Shell.print_error("unknown: #{target}")
         return
       end
 
       Shell.say "Usage: #{program_name} COMMAND [ARGS]", :cyan
-      Shell.say ''
-      print_command_list(self)
+      if full
+        each_command { |path, c| print_full_block(path, c) unless c.desc.empty? }
+      else
+        Shell.say ''
+        print_command_list(self)
+      end
       print_footer
     end
 
-    def print_namespace_help(prefix, ns)
+    def print_namespace_help(prefix, ns, full: false)
       Shell.say "Usage: #{program_name} #{prefix}:COMMAND [ARGS]", :cyan
-      Shell.say ''
-      print_command_list(ns, prefix)
+      if full
+        ns.each_command(prefix) { |path, c| print_full_block(path, c) unless c.desc.empty? }
+      else
+        Shell.say ''
+        print_command_list(ns, prefix)
+      end
       print_footer
     end
 
+    # One "task block" for the expanded listing: blank line separator
+    # then the standard per-command help (usage + desc + options + examples).
+    def print_full_block(path, cmd)
+      Shell.say ''
+      print_command_help(cmd, path)
+    end
+
     HOMEPAGE ||= 'https://github.com/dux/hammer'.freeze
 
     def print_footer
@@ -548,7 +584,7 @@ class Hammer
 
   # Inside a command's `proc do |opts| ... end`, call sibling commands:
   #
-  #   define :deploy do
+  #   task :deploy do
   #     proc do |opts|
   #       hammer :build
   #       hammer 'db:migrate', pretend: true
@@ -564,7 +600,7 @@ class Hammer
   # ----- block DSL -----------------------------------------------------
 
   # Define and run a CLI inline. Inside the block use
-  # `define :name do ... end`, `namespace`, and `load`.
+  # `task :name do ... end`, `namespace`, and `load`.
   #
   # Without a block: load ./Hammerfile if it exists, otherwise
   # auto-discover *_hammer.rb under Dir.pwd, then dispatch ARGV.
@@ -583,10 +619,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"
@@ -606,13 +663,15 @@ class Hammer
       Shell.say "create one - example:"
       puts
       Shell.say <<~RUBY
-        define :hello do
+        task :hello do
           desc 'say hello'
           proc do |opts|
             say.green "hello \#{opts[:args].first || 'world'}"
           end
         end
       RUBY
+      Shell.say ''
+      Shell.say "tip: run `#{File.basename($PROGRAM_NAME)} --ai` for AI-friendly Hammerfile authoring docs", :gray
       exit 1
     end
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: lux-hammer
 version: !ruby/object:Gem::Version
-  version: 0.2.3
+  version: 0.2.5
 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"
@@ -61,7 +62,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.8
+rubygems_version: 4.0.10
 specification_version: 4
 summary: Thor-inspired tiny CLI builder
 test_files: []