lux-hammer 0.3.21 → 0.3.23

data/recipes/llm.rb

@@ -7,7 +7,9 @@ desc <<~TXT
 
   Namespaces:
     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)
+    todo     per-project task queue for agents (./LLM_TODO.local.md)
 
   Commands:
     usage    subscription limits and per-model token usage
@@ -23,6 +25,7 @@ require 'set'
 # checkout still load matching lib/, not an older installed gem copy).
 _llm_root = File.dirname(File.realpath(__FILE__))
 require File.join(_llm_root, 'lib/llm/usage')
+require File.join(_llm_root, 'lib/llm/plan')
 
 STORE        ||= ENV['CLAUDE_MEMORY_STORE'] || File.expand_path('~/dev/ai/memory')
 VALID_TYPES  ||= %w[user feedback project reference].freeze
@@ -40,10 +43,10 @@ task :usage do
     `~/.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 'llm usage'
-  example 'llm usage month'
-  example 'llm usage --json'
-  example 'llm usage --provider grok'
+  example 'usage'
+  example 'usage month'
+  example 'usage --json'
+  example 'usage --provider grok'
 
   # :period is declared first on purpose — the parser fills un-set scalar opts
   # from positionals in declaration order, so `llm usage month` must reach
@@ -98,6 +101,17 @@ task :wrap do
     inserts for you (history recall, autocomplete, menu picks) will not show up, and
     nothing is captured while the program has echo off in canonical mode (sudo, ssh).
 
+    A line starting with ! is taken over: nothing reaches the wrapped program, the line
+    runs in $SHELL here, and the bar grows to show where it ran, what ran and what it
+    printed. That is a shell round trip instead of a tool call, a permission check and a
+    model turn - and it costs no context either, since the agent is never told.
+
+    Output stays up until you type anything at all, and a bare ! clears it too. Long
+    output is cut to the rows there are, and a command still running after 10s is killed,
+    since the wrapper is stopped while one runs. `cd` is handled here so that it sticks,
+    and moves nothing but the wrapper. Type !! to send a literal ! to the program instead,
+    which is how you reach Claude Code's own bash mode; a leading space does the same.
+
     Keys are decoded from plain bytes, the kitty keyboard protocol and xterm
     modifyOtherKeys, since a program can ask the terminal for any of the three (Claude
     Code turns on the last two). Mouse reports, focus events, arrows and Ctrl-<key> are
@@ -108,27 +122,59 @@ task :wrap do
 
     Put `--` before the wrapped command when it has flags of its own, otherwise they are
     parsed as flags to `llm wrap`.
+
+    With no command at all, the commands in ~/.config/hammer/llm-wrap.txt are offered in
+    an arrow-key picker instead. That file is plain text, one command per line. A line
+    starting with # is dropped, and a line with no letter in it stays on screen but
+    cannot be picked - so blanks and ---- rules group the list without being in the way.
+    `--config` opens it in $EDITOR, writing a starting set the first time.
   D
-  example 'llm wrap claude'
-  example 'llm wrap -- claude --resume'
-  example 'llm wrap --lines 5 -- bash -l'
+  example 'wrap'
+  example 'wrap --config'
+  example 'wrap claude'
+  example 'wrap -- claude --resume'
+  example 'wrap --lines 5 -- bash -l'
 
   # `positional: false` is load-bearing: the parser fills un-set scalar opts
   # from positionals in declaration order, so without it `llm wrap claude`
-  # would hand "claude" to --lines and die on the integer cast.
+  # would hand "claude" to --lines and die on the integer cast. `--config` is
+  # boolean, which the parser skips over, so it needs no such guard.
   opt :lines, type: :integer, default: 3, positional: false,
               desc: 'how many recent prompts to pin', placeholder: 'N'
+  opt :config, type: :boolean, desc: 'open the command list in $EDITOR'
 
   proc do |opts|
-    cmd = Array(opts[:args])
-    error 'usage: llm wrap [--lines N] [--] <command> [args...]' if cmd.empty?
-
     # Required lazily - llm.rb also runs as a per-prompt hook (`llm prompt
     # hook`), which should not pay to load pty/io-console. `_llm_root` is a
     # local from the file scope; the block closes over it (instance_exec
     # rebinds self, not locals).
     require File.join(_llm_root, 'lib/llm/wrap')
 
+    if opts[:config]
+      editor = ENV['EDITOR'] || ENV['VISUAL']
+      error '$EDITOR not set' unless editor
+      say.green "created #{LlmWrap::Config.path}" if LlmWrap::Config.seed
+      exit system(editor, LlmWrap::Config.path) ? 0 : 1
+    end
+
+    cmd = Array(opts[:args])
+
+    # Nothing asked for: offer the list rather than a usage error. The picker
+    # shows each line as it was written - re-joining a split argv would quote
+    # it back differently from what is in the file.
+    if cmd.empty?
+      LlmWrap::Config.seed
+      choices = LlmWrap::Config.lines
+      unless choices.any? { |line| LlmWrap::Config.runnable?(line) }
+        error "no commands in #{LlmWrap::Config.path} - add one with: llm wrap --config"
+      end
+
+      idx = choose('wrap which command?', choices, skip: ->(line) { !LlmWrap::Config.runnable?(line) })
+      next say.gray('cancelled') unless idx
+
+      cmd = LlmWrap::Config.argv(choices[idx])
+    end
+
     # The wrapper renames itself after the program it runs, so that a pane
     # watcher can still see which agent is in there - which leaves nothing
     # behind that says how the pane was started. This is that: the invocation
@@ -179,7 +225,7 @@ namespace :memory do
 
   task :list do
     desc 'List stored memories with type and one-line description'
-    example 'llm memory list'
+    example 'memory list'
 
     proc do
       files = Dir[File.join(STORE, '*.md')].sort
@@ -199,7 +245,7 @@ namespace :memory do
 
   task :read do
     desc 'Print the full content of a memory (frontmatter + body)'
-    example 'llm memory read user-role'
+    example 'memory read user-role'
 
     proc do |opts|
       name = opts[:args].first
@@ -251,7 +297,7 @@ namespace :memory do
 
   task :delete do
     desc 'Delete a memory by name'
-    example 'llm memory delete old-fact'
+    example 'memory delete old-fact'
 
     proc do |opts|
       name = opts[:args].first
@@ -265,7 +311,7 @@ namespace :memory do
 
   task :search do
     desc 'Search memory bodies for a query string (case-insensitive)'
-    example 'llm memory search react'
+    example 'memory search react'
 
     proc do |opts|
       query = opts[:args].first
@@ -287,6 +333,287 @@ namespace :memory do
   end
 end
 
+TODO_GUIDE ||= <<~TXT
+  Per-project task queue in ./LLM_TODO.local.md - workable by humans and any agent.
+
+  Human usage:
+    llm todo:add "fix login redirect"   queue a task (pipe stdin for bulk / multi-line)
+    llm todo:list                       tasks by id, counts, format warnings
+    llm todo:pop + llm todo:done        take / finish a single task by hand
+
+    Edit the file freely: only the `# todo`, `# doing` and `# done` sections are
+    managed. `# plan`, `# idea` and any prose stay untouched. A task starts with
+    `*` at the line start and runs until the next `*` or header; when finished it
+    moves to `# done` verbatim.
+
+  LLM usage - one of these lines is the whole prompt:
+    "Run `llm todo go` and follow its output."               work through every task
+    "Run `llm todo pop`, do the task, run `llm todo done`."  do a single task
+
+    Task text is printed raw on stdout. `todo go` repeats the protocol after each
+    task and says when the queue is empty; `todo pop` re-prints the task in
+    progress, so an interrupted agent resumes instead of skipping ahead.
+TXT
+
+task :todo do
+  desc <<~D
+    How the todo queue works, for humans and LLMs.
+
+    #{TODO_GUIDE}
+  D
+  example 'todo'
+
+  proc do
+    say TODO_GUIDE
+    say ''
+    self.class.print_help 'todo:'
+  end
+end
+
+namespace :todo do
+  # Same story as :memory - helpers must live inside the namespace block.
+  private
+
+  TODO_FILE     ||= 'LLM_TODO.local.md'
+  TODO_SECTIONS ||= { todo: 'todo', doing: 'doing', done: 'done' }.freeze
+
+  def todo_path
+    File.join(Dir.pwd, TODO_FILE)
+  end
+
+  # Exact title match on purpose - "# done ideas" must stay an unmanaged section.
+  def todo_section_key(title)
+    case title.strip.downcase
+    when 'todo', 'pending'                     then :todo
+    when 'doing', 'in progress', 'in-progress' then :doing
+    when 'done', 'completed'                   then :done
+    end
+  end
+
+  # The tool manages only the `# todo`, `# doing` and `# done` sections (any
+  # heading level). Inside them a task starts at a `*` or `-` bullet in the
+  # first column and runs until the next bullet or header, so tasks can span
+  # multiple lines and move between sections verbatim. Every other section
+  # (`# plan`, `# idea`, ...) and any preamble is kept as-is and never touched.
+  # Returns [tasks, nodes]; nodes reproduce the document layout for todo_save.
+  def todo_parse
+    tasks = { todo: [], doing: [], done: [] }
+    nodes = []
+    return [tasks, nodes] unless File.file?(todo_path)
+
+    section = nil # managed section key, nil while inside a raw chunk
+    current = nil # lines of the task being collected
+
+    flush_task = lambda do
+      tasks[section] << current.join("\n").rstrip if current
+      current = nil
+    end
+
+    File.foreach(todo_path) do |raw|
+      line = raw.chomp
+      if (m = line.match(/^#+\s*(\S.*?)\s*$/))
+        flush_task.call
+        section = todo_section_key(m[1])
+        if section
+          nodes << [:section, section] unless nodes.include?([:section, section])
+        else
+          nodes << [:raw, [line]]
+        end
+      elsif section
+        if line =~ /^[-*]\s+(.*)$/
+          flush_task.call
+          current = [$1.strip]
+        elsif current
+          current << line.rstrip
+        end
+      else
+        nodes << [:raw, []] unless nodes.last && nodes.last[0] == :raw
+        nodes.last[1] << line.rstrip
+      end
+    end
+    flush_task.call
+    [tasks, nodes]
+  end
+
+  # Rewrite: managed sections in canonical form, raw chunks verbatim, original
+  # order kept. Managed sections missing from the file are appended at the end.
+  def todo_save(tasks, nodes)
+    order = nodes + (TODO_SECTIONS.keys - nodes.map { |t, v| v if t == :section }).map { |k| [:section, k] }
+
+    File.open(todo_path, 'w') do |io|
+      order.each_with_index do |(type, value), i|
+        io.puts unless i.zero?
+        if type == :section
+          io.puts "# #{TODO_SECTIONS[value]}"
+          tasks[value].each do |text|
+            io.puts
+            io.puts "* #{text}"
+          end
+        else
+          lines = value.dup
+          lines.pop while lines.any? && lines.last.empty?
+          lines.each { |l| io.puts l }
+        end
+      end
+    end
+  end
+
+  # One-line label for confirmations - multi-line tasks show their first line.
+  def todo_label(text)
+    first, rest = text.split("\n", 2)
+    rest ? "#{first} ..." : first
+  end
+
+  # Format sanity check for hand-edited files. Returns warning strings.
+  def todo_lint(tasks)
+    warns   = []
+    seen    = Hash.new(0)
+    section = :preamble
+    File.foreach(todo_path) do |raw|
+      line = raw.chomp
+      if (m = line.match(/^#+\s*(\S.*?)\s*$/))
+        key       = todo_section_key(m[1])
+        section   = key || :other
+        seen[key] += 1 if key
+      elsif section == :preamble && line =~ /^[-*]\s/
+        warns << "ignored bullet before any section header: #{line}"
+      end
+    end
+    TODO_SECTIONS.each_key do |key|
+      warns << "duplicate '# #{key}' sections - their tasks are merged" if seen[key] > 1
+      warns << "missing '# #{key}' section - will be added on next write" if seen[key].zero?
+    end
+    warns << "#{tasks[:doing].length} tasks in doing - expected at most 1" if tasks[:doing].length > 1
+    warns
+  end
+
+  task :add do
+    desc <<~DESC
+      Add task(s) to ./#{TODO_FILE} (created on first add).
+
+      Text comes from the argument (one task), or from stdin - there a `*` at
+      the start of a line begins a new task and following lines belong to it,
+      so multi-line tasks and whole lists can be piped in at once.
+    DESC
+    example 'todo add "migrate the user model to Sequel"'
+    example 'cat tasks.md | llm todo add'
+    opt :text, desc: 'task text (or pipe tasks on stdin)'
+
+    proc do |opts|
+      # unquoted multi-word input lands in :text + :args - join it back
+      arg = [opts[:text], *opts[:args]].compact.join(' ').strip
+      if arg.empty?
+        new_tasks = []
+        opts[:stdin].to_s.split("\n").each do |line|
+          if line =~ /^[-*]\s+(.*)$/
+            new_tasks << [$1.strip]
+          elsif new_tasks.any?
+            new_tasks.last << line.rstrip
+          elsif line.strip != ''
+            new_tasks << [line.rstrip]
+          end
+        end
+        new_tasks = new_tasks.map { |lines| lines.join("\n").rstrip }.reject(&:empty?)
+      else
+        new_tasks = [arg]
+      end
+      error 'usage: llm todo add <text> (or pipe tasks on stdin)' if new_tasks.empty?
+
+      tasks, nodes = todo_parse
+      tasks[:todo].concat new_tasks
+      todo_save tasks, nodes
+      new_tasks.each { |t| say "added: #{todo_label(t)}", :green }
+    end
+  end
+
+  task :pop do
+    desc <<~DESC
+      Print the current task and stop there - one task, no loop.
+
+      Moves the first todo task to doing if nothing is doing yet. Prints only
+      the raw task text (agent-friendly stdout). Re-running without `todo done`
+      prints the same task again, so an interrupted agent resumes instead of
+      starting the next one. Exits 1 when the list is empty.
+    DESC
+    example 'todo pop'
+
+    proc do
+      tasks, nodes = todo_parse
+      if tasks[:doing].empty?
+        error 'todo list is empty' if tasks[:todo].empty?
+        tasks[:doing] << tasks[:todo].shift
+        todo_save tasks, nodes
+      end
+      puts tasks[:doing].first
+    end
+  end
+
+  task :go do
+    desc <<~DESC
+      Agent entry point: work through the whole todo list.
+
+      Prints the current task (pop) followed by the loop protocol, so telling
+      any agent "run llm todo go" is enough to drain the queue. When the list
+      is empty it says so and tells the agent to stop and summarize.
+    DESC
+    example 'todo go'
+
+    proc do
+      tasks, nodes = todo_parse
+      if tasks[:doing].empty? && tasks[:todo].empty?
+        say 'All tasks done - stop the loop and summarize what was done.'
+        next
+      end
+      if tasks[:doing].empty?
+        tasks[:doing] << tasks[:todo].shift
+        todo_save tasks, nodes
+      end
+      say "TASK: #{tasks[:doing].first}"
+      say ''
+      say 'Do this task fully and verify it. Then run `llm todo done`, and `llm todo go` for the next one.'
+    end
+  end
+
+  task :done do
+    desc 'Mark the in-progress task as done'
+    example 'todo done'
+
+    proc do
+      tasks, nodes = todo_parse
+      error 'no task in progress (run: llm todo pop)' if tasks[:doing].empty?
+      text = tasks[:doing].shift
+      tasks[:done] << text
+      todo_save tasks, nodes
+      say "done: #{todo_label(text)}", :green
+    end
+  end
+
+  task :list do
+    alt :inspect
+    desc 'Inspect the todo file: tasks by id, counts, format validity warnings'
+    example 'todo list'
+
+    proc do
+      error "no #{TODO_FILE} in #{Dir.pwd} (run: llm todo add <text>)" unless File.file?(todo_path)
+      tasks, = todo_parse
+      id = 0
+      TODO_SECTIONS.each do |key, title|
+        say "#{title}:", :cyan
+        color = { todo: nil, doing: :yellow, done: :gray }[key]
+        tasks[key].each do |text|
+          first, *rest = text.split("\n")
+          say "#{(id += 1).to_s.rjust(3)}. #{first}", color
+          rest.each { |l| say "     #{l}", color }
+        end
+        say '  (none)', :gray if tasks[key].empty?
+      end
+      say ''
+      say "#{tasks[:todo].length} todo, #{tasks[:doing].length} doing, #{tasks[:done].length} done"
+      todo_lint(tasks).each { |w| say "warning: #{w}", :yellow }
+    end
+  end
+end
+
 namespace :prompt do
   TOKEN_PATTERN        ||= /[a-z0-9_-]+/.freeze
   TOKEN_LINE_RE        ||= /\A(?:\s*:[a-z0-9_-]+)+\s*\z/.freeze
@@ -524,8 +851,8 @@ namespace :prompt do
 
   task :expand do
     desc 'Expand prompt token(s) and print the resulting context'
-    example 'llm prompt:expand :foo :bar'
-    example 'llm prompt:expand foo:'
+    example 'prompt:expand :foo :bar'
+    example 'prompt:expand foo:'
 
     proc do |opts|
       input = opts[:args].join(' ')
@@ -561,3 +888,104 @@ namespace :prompt do
     end
   end
 end
+
+# The namespace's sibling task: `llm plan` explains the thing, `llm plan:*`
+# does it. The command list underneath is hammer's own, not a copy.
+task :plan do
+  desc 'How the /plan bundle apply works: logic, bundle format, exit codes'
+  example 'plan'
+
+  proc do
+    say LlmPlan.readme
+    say ''
+    self.class.print_help 'plan:'
+  end
+end
+
+namespace :plan do
+  # Helpers live inside the namespace block for the same reason as :memory -
+  # a top-level `helpers do` lands on the root class, which namespaces do not
+  # inherit from.
+  private
+
+  def load_bundle(opts)
+    path = opts[:args].first
+    error 'usage: llm plan:<apply|check|verify|revert> ./tmp/plan-[SLUG].json' unless path
+    LlmPlan::Bundle.new(path)
+  rescue LlmPlan::Error => e
+    error e.message
+  end
+
+  # Hammer owns colour (and turns it off for a non-tty), so hand its painter
+  # to the report rather than teaching the report about ANSI.
+  def render(outcome)
+    report = LlmPlan::Report.new(outcome, paint: Hammer::Shell.method(:paint))
+    report.lines.each { |text, color| say text, color }
+  end
+
+  def run_verify(runner)
+    result = runner.verify { |cmd| say "  > #{cmd}", :cyan }
+    result.ok ? say('  verify ok', :green) : say("  FAIL #{result.failed_command}", :red)
+    result
+  end
+
+  task :apply do
+    # Composed from plan.md rather than written out again - see `llm plan`.
+    desc ['Apply a /plan bundle: sha1-checked edits now, drift handed back to you.',
+          "The bundle, normally ./tmp/plan-[SLUG].json:\n\n#{LlmPlan.section('The bundle')}",
+          LlmPlan.section('Drift'),
+          LlmPlan.section('Exit codes')].join("\n\n")
+    example 'plan:apply ./tmp/plan-note-anchor.json'
+
+    proc do |opts|
+      bundle  = load_bundle(opts)
+      runner  = LlmPlan::Runner.new(bundle)
+      outcome = runner.apply
+
+      render outcome
+      outcome.verify = run_verify(runner) if outcome.clean?
+
+      exit outcome.exit_code
+    end
+  end
+
+  task :check do
+    desc ['Dry run: the summary to read before approving a plan. Writes nothing.',
+          LlmPlan.section('Summary')].join("\n\n")
+    example 'plan:check ./tmp/plan-note-anchor.json'
+    example 'plan:check --md ./tmp/plan-note-anchor.json'
+
+    opt :md, type: :boolean, desc: 'emit the summary as markdown, to paste into a reply'
+
+    proc do |opts|
+      outcome = LlmPlan::Runner.new(load_bundle(opts)).apply(check_only: true)
+      opts[:md] ? puts(LlmPlan::MarkdownReport.new(outcome).to_s) : render(outcome)
+      exit outcome.exit_code
+    end
+  end
+
+  task :verify do
+    desc <<~D
+      Run only the bundle's verify commands.
+
+      For after you have closed a drift by hand, or fixed what a failing verify
+      caught. Exit 0 green, 20 failed.
+    D
+    example 'plan:verify ./tmp/plan-note-anchor.json'
+
+    proc do |opts|
+      exit run_verify(LlmPlan::Runner.new(load_bundle(opts))).ok ? 0 : 20
+    end
+  end
+
+  task :revert do
+    desc 'Undo an applied bundle from <slug>.bak: restore changed and deleted files, remove created ones.'
+    example 'plan:revert ./tmp/plan-note-anchor.json'
+
+    proc do |opts|
+      LlmPlan::Runner.new(load_bundle(opts)).revert.each { |path| say "  restored #{path}", :green }
+    rescue LlmPlan::Error => e
+      error e.message
+    end
+  end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: lux-hammer
 version: !ruby/object:Gem::Version
-  version: 0.3.21
+  version: 0.3.23
 platform: ruby
 authors:
 - Dino Reic
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-08-08 00:00:00.000000000 Z
+date: 2026-08-19 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/plan.rb"
 - "./recipes/lib/llm/usage.rb"
 - "./recipes/lib/llm/wrap.rb"
 - "./recipes/llm.rb"