lux-hammer 0.3.26 → 0.3.28

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: acc942b0818d0cc60a8cbe9a55fbf092665d6efcb46df209b2a8e9721aa1e190
-  data.tar.gz: 94baed7a0025611360d0315d084fd7432a1eb68d84302bfeaf0960ee0326aee7
+  metadata.gz: 48fd3473ba922f93fa0ebcc897d0bf6a88ec78283ed4436281d938a1297e53ac
+  data.tar.gz: 30eef033e89155cd82b362563e5f4dea0716551f56d686ae5c1fde16fc23170c
 SHA512:
-  metadata.gz: 486bb304e25a56faada26757651998d75e589fabca7402f499dc9cdd3228a90b30cc3fc7cda765d2cd34fc90eecc906208681c031e38628e0087f59eb5250af7
-  data.tar.gz: 87115686cf4bbdd6a47ed9a25e048cf811fe1c8071966e5ee3143b7fcafc286ff1480d00c5ba494e407fa9032b8e1b6dda43e8623c011ae9ffdbdf70e8a33612
+  metadata.gz: 7e3961d9aa6c6d89081ec6e1ee111346fab1944c8152644c7e22b300815bea3152606459c6d90e88592c8933021cc7c8ba75b262f8c5aebc4105b05816c0b9cb
+  data.tar.gz: 50fd5ecc020ecb0d31ad7f79d7d7dc5ae313e6646c30cdc0758b07bfbad1bfe145f50301215853b168cd3d79ccd5d66f0372551f405984ac87b0d026f13d047f

data/.version

@@ -1 +1 @@
-0.3.26
+0.3.28

data/AGENTS.md

@@ -22,8 +22,9 @@ usable as a library (`require 'lux-hammer'`, subclass `Hammer`, call
   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.
+* **Ruby >= 2.7** for `lib/` and `bin/`. Do not use language features
+  introduced after 2.7 there without flagging. Bundled recipes may sit
+  higher - the `llm` recipe needs >= 3.1 (endless methods, shorthand hash).
 * **`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
@@ -244,12 +245,15 @@ explicit ADR-level discussion. Keys:
 
 ## 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.
+* Program name in usage lines is the invocation as typed: a bare name
+  from PATH (`lux`), or a relative path that is runnable as printed
+  (`bin/foo`). An absolute `$PROGRAM_NAME` (PATH symlink, launchd unit,
+  shim) collapses to its basename - help never shows a full path, and
+  symlinks are never resolved (that once turned a typed `hammer` into
+  `gems/lux-hammer/bin/hammer`). 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 a relative name stays
+  relative to the cwd the user invoked from.
 * `hammer` (no args) routes to the `:default` built-in task, which
   falls through to `print_help(extended: false)` - the brief command
   listing with a top gray `lux-hammer VERSION - <homepage>` banner.
@@ -300,7 +304,10 @@ Task contracts:
   `--path NAME`, `--edit NAME`, `--run NAME [ARGS]` (use `--` to
   forward flags through). Bare invocation lists.
 * `h:init` - writes `Hammer::STARTER_HAMMERFILE` to `./Hammerfile`;
-  refuses if one exists.
+  refuses if one exists. `--script` writes `Hammer::STARTER_SCRIPT`
+  (shebang + one `hello` task) to stdout instead, or to a positional
+  TARGET with mode 0755. Both templates are single-quoted heredocs in
+  `lib/lux-hammer.rb` - the one source of truth, also rendered in help.
 * `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.
@@ -427,7 +434,8 @@ new code in this gem should show.
 
 ## Testing
 
-* Run: `bundle exec rake test`
+* Run: `bin/hammer test` (the `:test` task in this repo's Hammerfile -
+  there is no Rakefile)
 * 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`

data/README.md

@@ -634,6 +634,9 @@ Under the `h:` namespace:
 * `h:version` - print the lux-hammer version.
 * `h:recipes` - list / install / show / edit recipes.
 * `h:init` - write a starter Hammerfile in cwd (refuses if one exists).
+  `--script` prints a minimal standalone CLI to stdout instead (shebang
+  plus one `hello` task) - pipe it to a file and `chmod +x`, or name a
+  target to write and chmod in one step.
 * `h:json` - dump the CLI definition as JSON (tasks grouped like the
   bare listing, with desc/options/examples/aliases/needs/cron); `--all`
   includes the `h:` tasks, `--compact` minifies. Output is plain stdout
@@ -1135,7 +1138,16 @@ end
 ### `#!/usr/bin/env hammer` (single-file scripts)
 
 For a one-off CLI that lives as a single executable file, point the
-shebang straight at `hammer` - no `require`, no boilerplate:
+shebang straight at `hammer` - no `require`, no boilerplate. Start from
+the bundled template:
+
+```sh
+$ hammer h:init --script greet   # or: h:init --script > greet
+$ ./greet hello
+Hello from Hammer
+```
+
+Then fill it in - the body is plain Hammerfile DSL:
 
 ```ruby
 #!/usr/bin/env hammer
@@ -1398,7 +1410,7 @@ MyCli.hammer :greet, loud: true
 git clone https://github.com/dux/hammer
 cd lux-hammer
 bundle install
-bundle exec rake test
+bin/hammer test
 ```
 
 Tests live in `test/` and use minitest. Run a single file with

data/lib/hammer/builtins.rb

@@ -108,8 +108,24 @@ class Hammer
     def register_init(klass)
       klass.class_eval do
         task :init do
-          desc 'Write a starter Hammerfile in the current directory'
-          proc { Hammer::Builtins.write_starter_hammerfile }
+          desc <<~TXT
+            Write a starter Hammerfile in the current directory.
+
+            --script prints a minimal standalone CLI (shebang + one `hello`
+            task) to stdout instead - pipe it to a file, chmod +x, run it.
+            Name a TARGET to write and chmod in one step.
+          TXT
+          example 'h:init'
+          example 'h:init --script > mytool && chmod +x mytool'
+          example 'h:init --script mytool'
+          opt :script, type: :boolean, alias: :s, desc: 'print a standalone executable CLI (TARGET writes + chmod +x)'
+          proc do |opts|
+            if opts[:script]
+              Hammer::Builtins.write_starter_script(opts[:args].first)
+            else
+              Hammer::Builtins.write_starter_hammerfile
+            end
+          end
         end
       end
     end
@@ -237,6 +253,20 @@ class Hammer
       Shell.say "created #{target}", :green
     end
 
+    # `h:init --script`. No target -> stdout, so `> tool` works; with a
+    # target it lands executable. Never clobbers, same as the Hammerfile.
+    def write_starter_script(target = nil)
+      return puts(Hammer::STARTER_SCRIPT) unless target
+
+      if File.exist?(target)
+        Shell.print_error "#{target} already exists"
+        exit 1
+      end
+      File.write(target, Hammer::STARTER_SCRIPT)
+      File.chmod(0o755, target)
+      Shell.say "created #{target} (chmod +x)", :green
+    end
+
     # Implementations of the `recipes` task's action flags, plus the
     # no-flag listing view. Separate module so the task definition above
     # stays small.

data/lib/lux-hammer.rb

@@ -138,19 +138,14 @@ class Hammer
       @app_desc = text.to_s.rstrip
     end
 
-    # Program name shown in help/usage: the invocation path relative to cwd
-    # if the script lives inside it (e.g. `bin/foo` when invoked from the
-    # project root), otherwise the basename (e.g. `lux` for a globally
-    # installed bin in PATH).
+    # Program name shown in help/usage: the invocation as typed - a bare
+    # name from PATH (`lux`), or a relative path that is runnable as
+    # printed (`bin/foo`). Absolute paths (PATH symlinks, launchd units,
+    # shims) collapse to the basename - help never shows a full path.
     def default_program_name
       prog = $PROGRAM_NAME
-      return File.basename(prog) unless prog.include?('/')
-      # Resolve symlinks on both sides so e.g. macOS `/tmp` -> `/private/tmp`
-      # doesn't cause a false miss when comparing prefixes.
-      abs = File.realpath(prog) rescue File.expand_path(prog)
-      cwd = File.realpath(Dir.pwd) rescue Dir.pwd
-      return abs[(cwd.length + 1)..] if abs.start_with?("#{cwd}/")
-      File.basename(prog)
+      return File.basename(prog) if prog.start_with?('/')
+      prog.sub(%r{\A\./}, '')
     end
 
     # Define a command. Block runs in a CommandBuilder context and must
@@ -1118,6 +1113,20 @@ class Hammer
     end
   RUBY
 
+  # Minimal standalone CLI, dumped by `hammer h:init --script`. The
+  # shebang is what `shebang_script` sniffs for, so `chmod +x` is all
+  # that stands between this and a working binary.
+  STARTER_SCRIPT ||= <<~'RUBY'
+    #!/usr/bin/env hammer
+
+    desc 'My standalone CLI'
+
+    task :hello do
+      desc 'Print a greeting'
+      proc { say.green 'Hello from Hammer' }
+    end
+  RUBY
+
   # Default install dir used by install.sh and `hammer h:update`.
   SELF_UPDATE_DIR  ||= File.expand_path('~/.local/share/lux-hammer')
   SELF_UPDATE_REPO ||= 'https://github.com/dux/hammer.git'

data/recipes/lib/llm/browser.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+# Builds the commands `llm browser:*` hands to Bun. Stagehand is installed
+# globally with `bun add -g`, and Bun resolves imports from NODE_PATH, so the
+# TypeScript under browser/ can live here while the package lives in the
+# global store. Nothing in this module runs Bun or the network - that is what
+# keeps it testable.
+module LlmBrowser
+  GLOBAL_MODULES ||= File.join(Dir.home, '.bun/install/global/node_modules')
+  SCRIPT_DIR     ||= File.join(__dir__, 'browser')
+  RUNNER         ||= File.join(SCRIPT_DIR, 'run.ts')
+  PACKAGES       ||= %w[@browserbasehq/stagehand zod].freeze
+  CHROME         ||= '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome'
+
+  # Who answers Stagehand's act / observe / extract questions. claude and codex
+  # go through their CLIs (subscription, no API key); ollama is Stagehand's own
+  # provider talking to the local daemon.
+  LLMS ||= %w[claude codex ollama].freeze
+
+  # First backend whose name starts with the prefix: `c` is claude, `co` codex,
+  # `o` ollama. No prefix means claude.
+  def self.llm(prefix)
+    return LLMS.first if prefix.nil? || prefix.empty?
+    LLMS.find { |name| name.start_with?(prefix) }
+  end
+
+  def self.env
+    { 'NODE_PATH' => GLOBAL_MODULES }
+  end
+
+  def self.setup_argv
+    ['bun', 'add', '-g', *PACKAGES]
+  end
+
+  def self.run_argv(url, instructions = [], llm: 'claude', headed: false, shot: nil)
+    argv = ['bun', RUNNER, url, *instructions, '--llm', llm]
+    argv << '--headed' if headed
+    argv.push('--shot', shot) if shot
+    argv
+  end
+
+  def self.script_argv(path, extra = [])
+    ['bun', RUNNER, '--script', File.expand_path(path), *extra]
+  end
+
+  def self.installed?(modules: GLOBAL_MODULES)
+    PACKAGES.all? { |pkg| File.directory?(File.join(modules, pkg)) }
+  end
+
+  # What `browser:setup` reports: name => true/false, in the order it prints.
+  def self.check(modules: GLOBAL_MODULES, chrome: CHROME)
+    {
+      'bun'       => command?('bun'),
+      'stagehand' => installed?(modules: modules),
+      'chrome'    => File.exist?(chrome),
+      'claude'    => command?('claude'),
+      'codex'     => command?('codex'),
+      'ollama'    => command?('ollama'),
+    }
+  end
+
+  def self.command?(name)
+    ENV.fetch('PATH', '').split(File::PATH_SEPARATOR).any? { |dir| File.executable?(File.join(dir, name)) }
+  end
+end

data/recipes/lib/llm/launch.rb

@@ -4,7 +4,8 @@ require 'json'
 require 'pathname'
 
 # Builds the command `llm wrap:run` hands to LlmWrap: picks the agent CLI by
-# prefix and maps the generic -c / -f / -a switches to what that CLI takes.
+# prefix and maps the generic -c / -f switches to what that CLI takes. The
+# AGENTS.md chain is injected by default; -b (bare) leaves it out.
 module LlmLaunch
   Launch = Struct.new(:argv, :env, :files)
 
@@ -22,7 +23,7 @@ module LlmLaunch
                     agents: ->(_text, files) { { env: { 'OPENCODE_CONFIG_CONTENT' => { instructions: files }.to_json } } } },
   }.freeze
 
-  # Read AGENTS.md from the git root down on their own; -a only adds the
+  # Read AGENTS.md from the git root down on their own; we only add the
   # files above it for these. Claude reads CLAUDE.md, so it gets the chain.
   NATIVE_AGENTS ||= %w[codex grok opencode].freeze
 
@@ -33,13 +34,13 @@ module LlmLaunch
     TOOLS.keys.find { |name| name.start_with?(prefix) }
   end
 
-  def self.build(tool, extra = [], continue: false, full: false, agents: false, cwd: Dir.pwd, home: Dir.home)
+  def self.build(tool, extra = [], continue: false, full: false, bare: false, cwd: Dir.pwd, home: Dir.home)
     spec = TOOLS.fetch(tool)
     argv = [tool]
     argv.concat(spec[:continue]) if continue
     argv.concat(spec[:full]) if full
 
-    files = agents ? agents_files(tool, cwd: cwd, home: home) : []
+    files = bare ? [] : agents_files(tool, cwd: cwd, home: home)
     env = {}
     if files.any?
       added = spec[:agents].call(agents_text(files), files.map(&:to_s))

data/recipes/lib/llm/usage.rb

@@ -34,6 +34,11 @@ module LlmUsage
   GROK_LOG_PATH   ||= File.expand_path('~/.grok/logs/unified.jsonl')
   GROK_SESSION_GLOB ||= File.expand_path('~/.grok/sessions/**/signals.json')
   GROK_SUMMARY_GLOB ||= File.expand_path('~/.grok/sessions/**/summary.json')
+  GROK_AUTH_PATH  ||= File.expand_path('~/.grok/auth.json')
+  # Same endpoint grok's /usage pane hits. 1.0.13+ strips creditUsagePercent
+  # from the unified log, so the log is only a reset-time fallback.
+  GROK_BILLING_URL ||= 'https://cli-chat-proxy.grok.com/v1/billing?format=credits'
+  GROK_TOKEN_AUTH ||= 'xai-grok-cli'
   CLAUDE_SESSION_GLOB ||= File.expand_path('~/.claude/projects/**/*.jsonl')
   # Written by the statusline hook (~/.claude/statusline-command.sh) from its
   # `rate_limits` input; mtime is the observation time.
@@ -378,15 +383,15 @@ module LlmUsage
     return nil unless data.is_a?(Hash)
 
     config = data['config'] || data
-    week_pct = config['creditUsagePercent']
-    week_reset = config['billingPeriodEnd'] || config.dig('currentPeriod', 'end')
     build = Array(config['productUsage']).find { |p| p['product'] == 'GrokBuild' }
+    week_pct = (build && build['usagePercent']) || config['creditUsagePercent']
+    week_reset = config['billingPeriodEnd'] || config.dig('currentPeriod', 'end')
 
     UsageRow.new(
       name: 'Grok',
       session_pct: '-',
       session_reset: '-',
-      week_pct: format_pct(build ? build['usagePercent'] : week_pct),
+      week_pct: format_pct(week_pct),
       week_reset: format_reset_short(week_reset, now: now)
     )
   end
@@ -496,8 +501,59 @@ module LlmUsage
     [nil, note || fallback_note || 'codex: no local rate limits']
   end
 
-  def fetch_grok_usage
-    grok_log_billing_config
+  def fetch_grok_usage(now: Time.now, path: GROK_AUTH_PATH)
+    data, note = fetch_grok_oauth_usage(now: now, path: path)
+    return [data, note] if data
+
+    log_data, log_note = grok_log_billing_config
+    return [log_data, log_note] if log_data
+
+    [nil, [note, log_note].compact.join('; ')]
+  end
+
+  def fetch_grok_oauth_usage(now: Time.now, path: GROK_AUTH_PATH)
+    token = grok_oauth_token(now: now, path: path)
+    return [nil, 'grok: no usable auth token (run `grok login`)'] unless token
+
+    uri = URI(GROK_BILLING_URL)
+    response = Net::HTTP.start(uri.host, uri.port, use_ssl: true, open_timeout: 3, read_timeout: 5) do |http|
+      http.get(
+        uri.request_uri,
+        'Authorization' => "Bearer #{token}",
+        'Accept' => 'application/json',
+        'X-XAI-Token-Auth' => GROK_TOKEN_AUTH
+      )
+    end
+    return [nil, "grok: billing API returned #{response.code}"] unless response.is_a?(Net::HTTPSuccess)
+
+    data = JSON.parse(response.body)
+    return [nil, 'grok: billing API returned no config'] unless data.is_a?(Hash) && data['config'].is_a?(Hash)
+
+    [data, nil]
+  rescue JSON::ParserError
+    [nil, 'grok: billing API returned malformed JSON']
+  rescue StandardError => e
+    [nil, "grok: billing API unreachable (#{e.message})"]
+  end
+
+  # grok login writes one Hash per issuer (`https://auth.x.ai::<uuid>`).
+  # An expired token is treated as absent rather than refreshed here.
+  def grok_oauth_token(now: Time.now, path: GROK_AUTH_PATH)
+    creds = read_json(path)
+    return nil unless creds.is_a?(Hash)
+
+    creds.each_value do |entry|
+      next unless entry.is_a?(Hash)
+
+      token = entry['key']
+      next if token.nil? || token.empty?
+
+      expires_at = parse_time(entry['expires_at'])
+      next if expires_at && expires_at <= now
+
+      return token
+    end
+    nil
   end
 
   def codex_app_server_rate_limits

data/recipes/llm.rb

@@ -6,6 +6,7 @@ desc <<~TXT
   llm - personal LLM utility CLI
 
   Namespaces:
+    browser  drive a local Chrome with Stagehand, thinking through claude / codex / ollama
     memory   persistent memory store (backs the Claude Code memory plugin)
     plan     apply a /plan bundle - sha1 checked, drift aware
     prompt   token-prefix prompt expander (UserPromptSubmit hook + CLI)
@@ -13,7 +14,7 @@ desc <<~TXT
   Commands:
     usage    subscription limits and per-model token usage
     wrap     run a command with your last two prompts pinned to the screen
-    wrap:run start claude / codex / grok / opencode in wrap, same -c -f -a switches for all
+    wrap:run start claude / codex / grok / opencode in wrap, same -c -f -b switches for all
 TXT
 
 require 'fileutils'
@@ -27,6 +28,7 @@ _llm_root = File.dirname(File.realpath(__FILE__))
 require File.join(_llm_root, 'lib/llm/usage')
 require File.join(_llm_root, 'lib/llm/plan')
 
+BROWSER_LIB  ||= File.join(_llm_root, 'lib/llm/browser')
 STORE        ||= ENV['CLAUDE_MEMORY_STORE'] || File.expand_path('~/dev/ai/memory')
 VALID_TYPES  ||= %w[user feedback project reference].freeze
 
@@ -38,10 +40,13 @@ task :usage do
 
     Default view lists session and weekly windows side by side.
     Local Claude, Codex, and Grok sessions provide calendar day, week, and month token totals.
-    Reads Codex via `codex app-server`; Grok billing + tokens from `~/.grok/logs/unified.jsonl`
-    (inference_done events). Claude 5h/week windows come from the statusline snapshot at
-    `~/.cache/llm/claude-limits.json`, falling back to the OAuth usage API. `month` shows
-    Claude extra-usage credits (API only, and only when you've enabled them).
+    Reads Codex via `codex app-server`. Grok week credits come from the
+    `cli-chat-proxy` billing API (`~/.grok/auth.json`), falling back to
+    `~/.grok/logs/unified.jsonl` for the period end; tokens still sum
+    inference_done events in that log. Claude 5h/week windows come from the
+    statusline snapshot at `~/.cache/llm/claude-limits.json`, falling back to
+    the OAuth usage API. `month` shows Claude extra-usage credits (API only,
+    and only when you've enabled them).
   D
   example 'usage'
   example 'usage month'
@@ -198,22 +203,22 @@ namespace :wrap do
         -c  continue the last session here    claude/grok/opencode -c, codex resume --last
         -f  full permissions, no prompts      --dangerously-skip-permissions, --dangerously-bypass-
                                               approvals-and-sandbox, --always-approve, --auto
-        -a  AGENTS.md from ~ down to cwd      claude --append-system-prompt, codex -c
-                                              developer_instructions, grok --rules, opencode
-                                              inline config
+        -b  bare - no AGENTS.md injection     skips the default below
 
-      codex, grok and opencode read AGENTS.md from the git root down by themselves, so
-      -a only adds the files above the repo for them; claude gets the whole chain.
+      By default every AGENTS.md from ~ down to cwd is handed to the tool: claude
+      --append-system-prompt, codex -c developer_instructions, grok --rules, opencode
+      inline config. codex, grok and opencode read AGENTS.md from the git root down by
+      themselves, so they only get the files above the repo; claude gets the whole chain.
       Anything after `--` is handed to the tool untouched. `~/bin/ai` is this command.
     D
     example 'wrap:run'
     example 'wrap:run g -cf'
-    example 'wrap:run cod -ca'
+    example 'wrap:run cod -cb'
     example 'wrap:run c -- --model opus'
 
     opt :continue, type: :boolean, desc: 'continue the last session in this folder'
     opt :full,     type: :boolean, desc: 'full permissions, no approval prompts'
-    opt :agents,   type: :boolean, desc: 'inject AGENTS.md found from ~ down to cwd'
+    opt :bare,     type: :boolean, desc: 'bare agent - do not inject AGENTS.md'
 
     proc do |opts|
       require File.join(_llm_root, 'lib/llm/wrap')
@@ -225,11 +230,11 @@ namespace :wrap do
              error("unknown tool #{prefix.inspect} - one of #{LlmLaunch::TOOLS.keys.join(', ')}")
       extra = prefix ? args.drop(1) : args
 
-      launch = LlmLaunch.build(tool, extra, continue: opts[:continue], full: opts[:full], agents: opts[:agents])
+      launch = LlmLaunch.build(tool, extra, continue: opts[:continue], full: opts[:full], bare: opts[:bare])
       ENV.update(launch.env)
       say.gray "agents: #{launch.files.map { |f| f.to_s.sub(Dir.home, '~') }.join(', ')}" if launch.files.any?
 
-      flags = %i[continue full agents].select { |k| opts[k] }.map { |k| "--#{k}" }
+      flags = %i[continue full bare].select { |k| opts[k] }.map { |k| "--#{k}" }
       origin = ['llm', 'wrap:run', tool, *flags, '--', *extra]
       # Piped stdout is block-buffered and exec drops the buffer with the banner in it.
       $stdout.flush
@@ -385,6 +390,98 @@ namespace :memory do
   end
 end
 
+namespace :browser do
+  # Helpers live inside the namespace block for the same reason as in
+  # :memory - namespace subclasses do not see the recipe's root class. The
+  # recipe-level `_llm_root` local is out of reach in a def, hence the constant.
+  private
+
+  def browser_lib
+    require BROWSER_LIB
+    LlmBrowser
+  end
+
+  task :setup do
+    desc <<~D
+      Install Stagehand globally with bun and report what the browser tools can use.
+
+      Stagehand (@browserbasehq/stagehand) drives the installed Google Chrome over CDP.
+      Its act / observe / extract calls need a model: claude and codex answer through
+      their CLIs on your subscription, ollama through the local daemon. No API key.
+    D
+    example 'browser:setup'
+
+    proc do
+      lib = browser_lib
+      if lib.installed?
+        say.gray 'stagehand already installed'
+      else
+        say.gray lib.setup_argv.join(' ')
+        error 'bun add failed' unless system(*lib.setup_argv)
+      end
+      lib.check.each do |name, ok|
+        say "#{name.ljust(10)} #{ok ? 'ok' : 'missing'}", (ok ? :green : :red)
+      end
+    end
+  end
+
+  task :run do
+    desc <<~D
+      Open URL in a local Chrome and run act / observe / extract instructions in order.
+
+      Instructions are quoted strings prefixed with act:, observe: or extract:; a bare
+      string is an extract. One JSON object per instruction goes to stdout, progress to
+      stderr. Use it for other people's sites - multi-step flows, structured extraction,
+      forms and logins (--headed). For an app you develop use the chrome-devtools MCP:
+      console, network and perf live there. Nothing here sees inside a canvas.
+
+      Each model call spawns the CLI, so expect 10-20 s per instruction. Nothing is
+      cached locally. BROWSE_CLAUDE_MODEL (sonnet - haiku misses clicks), BROWSE_CODEX_MODEL
+      (codex default - set a small one) and BROWSE_OLLAMA_MODEL (qwen2.5-coder) pick the model.
+    D
+    example 'browser:run https://example.com "extract: the heading and the first link href"'
+    example 'browser:run https://x.com "act: click Sign in" "extract: the form field labels" --headed'
+    example 'browser:run https://x.com "observe: what can be clicked" --llm codex'
+
+    opt :llm,    default: 'claude', positional: false, desc: 'claude | codex | ollama (prefix ok)'
+    opt :headed, type: :boolean, desc: 'visible Chrome window - logins, watching it work'
+    opt :shot,   positional: false, desc: 'save a PNG of the final page to this path'
+
+    proc do |opts|
+      lib = browser_lib
+      url, *instructions = Array(opts[:args])
+      error 'usage: llm browser:run <url> ["act: ..."] ["extract: ..."] [--llm claude|codex|ollama] [--headed] [--shot out.png]' unless url
+      error 'run `llm browser:setup` first' unless lib.installed?
+      llm = lib.llm(opts[:llm]) || error("unknown llm #{opts[:llm].inspect} - one of #{lib::LLMS.join(', ')}")
+
+      $stdout.flush
+      exit(system(lib.env, *lib.run_argv(url, instructions, llm: llm, headed: opts[:headed], shot: opts[:shot])) ? 0 : 1)
+    end
+  end
+
+  task :script do
+    desc <<~D
+      Run an ad-hoc Stagehand script with Bun, Stagehand resolvable from the global store.
+
+      The script imports open() from recipes/lib/llm/browser/lib.ts and gets a ready
+      { stagehand, page, close }. Anything after the file is left in process.argv.
+    D
+    example 'browser:script ./scrape.ts'
+    example 'browser:script ./scrape.ts -- --since 2026-01-01'
+
+    proc do |opts|
+      lib = browser_lib
+      path, *extra = Array(opts[:args])
+      error 'usage: llm browser:script <file.ts> [args...]' unless path
+      error "no such file: #{path}" unless File.file?(File.expand_path(path))
+      error 'run `llm browser:setup` first' unless lib.installed?
+
+      $stdout.flush
+      exec(lib.env, *lib.script_argv(path, extra))
+    end
+  end
+end
+
 namespace :prompt do
   TOKEN_PATTERN        ||= /[a-z0-9_-]+/.freeze
   TOKEN_LINE_RE        ||= /\A(?:\s*:[a-z0-9_-]+)+\s*\z/.freeze

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: lux-hammer
 version: !ruby/object:Gem::Version
-  version: 0.3.26
+  version: 0.3.28
 platform: ruby
 authors:
 - Dino Reic
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-08-27 00:00:00.000000000 Z
+date: 2026-09-09 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: minitest
@@ -55,6 +55,7 @@ files:
 - "./lib/lux-hammer.rb"
 - "./recipes/deploy.rb"
 - "./recipes/git-helper.rb"
+- "./recipes/lib/llm/browser.rb"
 - "./recipes/lib/llm/launch.rb"
 - "./recipes/lib/llm/plan.rb"
 - "./recipes/lib/llm/usage.rb"