hiiro 0.1.71 → 0.1.72

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ff87ba519316c2de7ddfada0355b3961219bafc7d1f8c6bf9963f2a63d22783d
-  data.tar.gz: 47b52e2550d78babe9227c5ff729fbbca7fbbd87e44b6fcb25494d1dd136fb50
+  metadata.gz: 5f96d3544bba42161e843e3e9478eb09a72b0cf32b2ec0736ef9a3e074d247cc
+  data.tar.gz: 8cb67c7ae3a7de600bb43b75b8399fc998359a7ac869241485a582561d8225a5
 SHA512:
-  metadata.gz: 2be2cbd5456bf9d88100ec1568f7a254090f55ce5bdd0dd11692b95fb65f0c88525899fb0bc2d53f5a50dfa666413f41bdf722375d3951a1b77c44f1509dc164
-  data.tar.gz: 3085116536819a63eefc3b6cc5a28a990d4ef2ce160f1a25ee5738a8035ca41ee154cd0e80a9eeb3018e67e4e3f5c308628076fc3c8c3dc88252137afca242bb
+  metadata.gz: 3397f01c85baa33ad040dff94823fec9ed78475aafe2b18a008df3aea3766c2f55ef622988b2b9a4b8b0e34ed0679015bafecf76b295f744d72449c127680844
+  data.tar.gz: 8c9fd7fe66febe8af0eca35c980fbf550ec2fd1461d845be4d0f481825fb77aa0e22075753db294f0d5de79a3f3f23cef3da7859d0fe1d4a983d77db7d0f4018

data/CLAUDE.md

@@ -78,11 +78,164 @@ hiiro.add_subcmd(:pwd) do |*args, **values|
 end
 ```
 
+## Creating Subcommands
+
+There are two ways to add subcommands to Hiiro:
+
+### 1. External Bin File (Preferred)
+
+Create a new executable `bin/h-<name>` that uses `Hiiro.run`:
+
+```ruby
+#!/usr/bin/env ruby
+require 'hiiro'
+
+Hiiro.run(*ARGV, plugins: [:Tasks]) {
+  add_subcmd(:list) {
+    puts "Listing items..."
+  }
+
+  add_subcmd(:add) { |name, path=nil|
+    puts "Adding #{name} at #{path}"
+  }
+
+  add_subcmd(:remove) { |name=nil|
+    if name.nil?
+      puts "Usage: h mycommand remove <name>"
+      next
+    end
+    puts "Removed #{name}"
+  }
+}
+```
+
+This creates commands like `h mycommand list`, `h mycommand add foo /path`.
+
+### 2. Nested Subcommands via build_hiiro
+
+For complex command hierarchies with shared state, create a nested Hiiro instance:
+
+```ruby
+def self.add_subcommands(hiiro)
+  hiiro.add_subcmd(:task) do |*args|
+    tm = TaskManager.new(hiiro, scope: :task)
+    build_hiiro(hiiro, tm).run
+  end
+end
+
+def self.build_hiiro(parent_hiiro, tm)
+  bin_name = [parent_hiiro.bin, parent_hiiro.subcmd || ''].join('-')
+
+  Hiiro.init(bin_name:, args: parent_hiiro.args) do |h|
+    h.add_subcmd(:list) { tm.list }
+    h.add_subcmd(:start) { |name| tm.start_task(name) }
+    h.add_subcmd(:switch) { |name=nil|
+      name ||= tm.select_task_interactive
+      tm.switch_to_task(tm.task_by_name(name))
+    }
+  end
+end
+```
+
+This pattern:
+- Passes remaining args from parent to child via `args: parent_hiiro.args`
+- Allows shared state (like `tm`) across all nested subcommands
+- Creates commands like `h task list`, `h task start foo`
+
+## Library Components (lib/)
+
+The `lib/hiiro.rb` file and `lib/hiiro/` directory contain the core framework classes:
+
+### Hiiro (lib/hiiro.rb)
+
+Main entry point with class methods:
+- `Hiiro.run(*ARGV, plugins: [...]) { ... }` - Initialize and run immediately
+- `Hiiro.init(*ARGV, plugins: [...]) { ... }` - Initialize without running (returns hiiro instance)
+
+Instance methods available in subcommand blocks:
+- `git` - Returns `Hiiro::Git` instance for git operations
+- `sk(lines)` - Interactive selection via skim
+- `pins` - Key-value storage per command
+- `todo_manager` - Todo item management
+- `history` - Command history tracking
+- `attach_method(name, &block)` - Add methods to hiiro instance dynamically
+- `make_child(subcmd, *args)` - Create nested Hiiro for sub-subcommands
+
+### Hiiro::PrefixMatcher (lib/hiiro/prefix_matcher.rb)
+
+Handles abbreviation matching for commands and items:
+
+```ruby
+matcher = Hiiro::PrefixMatcher.new(items, :name)
+result = matcher.find("pre")     # Find items where name starts with "pre"
+result.match?                     # Any matches?
+result.one?                       # Exactly one match?
+result.ambiguous?                 # Multiple matches?
+result.first&.item                # Get first matching item
+result.resolved&.item             # Get exact or single match
+
+# Path-based matching for hierarchical names (e.g., "task/subtask")
+result = matcher.resolve_path("t/s")
+```
+
+### Hiiro::Git (lib/hiiro/git.rb)
+
+Git operations wrapper with submodules for branches, worktrees, remotes, and PRs:
+
+```ruby
+git = hiiro.git
+git.root                          # Repository root path
+git.branch                        # Current branch name
+git.branches                      # List all branches
+git.worktrees                     # List all worktrees
+git.add_worktree(path, branch:)   # Create worktree
+git.move_worktree(from, to)       # Rename worktree
+git.current_pr                    # Get current PR info
+```
+
+### Hiiro::Sk (lib/hiiro/sk.rb)
+
+Integration with `sk` (skim) fuzzy finder:
+
+```ruby
+selected = Hiiro::Sk.select(["option1", "option2", "option3"])
+# Returns selected string or nil if cancelled
+
+value = Hiiro::Sk.map_select({ "Display 1" => "value1", "Display 2" => "value2" })
+# Shows keys, returns corresponding value
+```
+
+### Hiiro::TodoManager (lib/hiiro/todo.rb)
+
+Todo item management with task association:
+
+```ruby
+tm = Hiiro::TodoManager.new
+tm.add("Fix bug", tags: "urgent", task_info: { task_name: "feature" })
+tm.start(0)                       # Mark item as started
+tm.done(0)                        # Mark item as done
+tm.active                         # Items not done/skipped
+tm.filter_by_task("feature")      # Items for specific task
+```
+
+### Hiiro::History (lib/hiiro/history.rb)
+
+Command history tracking with tmux/git/task context:
+
+```ruby
+History.track(cmd: full_command, hiiro: self)  # Auto-called after commands
+History.by_task("feature")                      # Filter by task
+History.by_branch("main")                       # Filter by git branch
+History.by_session("work")                      # Filter by tmux session
+```
+
 ## Key Files
 
 - `bin/h` - Core framework (~420 lines)
 - `bin/h-*` - External subcommands (tmux wrappers, video operations)
 - `plugins/*.rb` - Reusable plugin modules (Pins, Project, Task, Tmux, Notify)
+- `lib/hiiro.rb` - Main Hiiro class and Runners
+- `lib/hiiro/*.rb` - Supporting classes (Git, PrefixMatcher, Sk, Todo, History)
 
 ## External Dependencies
 

data/bin/h-branch

@@ -241,8 +241,8 @@ checkout_branch = lambda { |branch = nil, *args|
   system('git', 'checkout', branch, *args)
 }
 
-hiiro.add_subcmd(:checkout, checkout_branch)
-hiiro.add_subcmd(:co, checkout_branch)
+hiiro.add_subcmd(:checkout, &checkout_branch)
+hiiro.add_subcmd(:co, &checkout_branch)
 
 remove_branch = lambda { |branch = nil, *args|
   unless branch
@@ -275,14 +275,35 @@ hiiro.add_subcmd(:duplicate) { |new_name = nil, source = nil|
   puts "Created branch '#{new_name}' from '#{source}'"
 }
 
+hiiro.add_subcmd(:test) { |*args|
+  opts = Hiiro::Options.parse(args) do
+    option :remote, short: 'r', default: 'origin', desc: 'Remote name'
+    option :from, short: 'f', desc: 'Local branch or commit to push'
+    option :to, short: 't', desc: 'Remote branch name'
+    flag :force, short: 'F', desc: 'Force push'
+    flag :set_upstream, short: 'u', desc: 'Set upstream tracking'
+  end
+
+  {
+    remote_as_method: opts.remote,
+    remote_as_sym_key: opts[:remote],
+    remote_as_string_key: opts['remote'],
+    force_as_method: opts.force,
+    force_as_sym_key: opts[:force],
+    force_as_string_key: opts['force'],
+  }.each do |k,v|
+    puts "#{k} => #{v}"
+  end
+}
+
 hiiro.add_subcmd(:push) { |*args|
-  opts = Hiiro::Options.new(args) do
+  opts = Hiiro::Options.parse(args) do
     option :remote, short: 'r', default: 'origin', desc: 'Remote name'
     option :from, short: 'f', desc: 'Local branch or commit to push'
     option :to, short: 't', desc: 'Remote branch name'
     flag :force, short: 'F', desc: 'Force push'
     flag :set_upstream, short: 'u', desc: 'Set upstream tracking'
-  end.parse!
+  end
 
   local_ref = opts[:from] || hiiro.git.branch
   remote_branch = opts[:to] || local_ref

data/lib/hiiro/options.rb

@@ -1,167 +1,192 @@
 class Hiiro
   class Options
-    class Definition
-      attr_reader :name, :short, :type, :default, :desc, :multi
-
-      def initialize(name, short: nil, type: :string, default: nil, desc: nil, multi: false)
-        @name = name.to_sym
-        @short = short&.to_s
-        @type = type
-        @default = default
-        @desc = desc
-        @multi = multi
-      end
-
-      def flag?
-        type == :flag
-      end
-
-      def long_form
-        "--#{name.to_s.tr('_', '-')}"
-      end
-
-      def short_form
-        short ? "-#{short}" : nil
-      end
-
-      def match?(arg)
-        arg == long_form || arg == short_form
-      end
+    attr_reader :definitions
 
-      def coerce(value)
-        case type
-        when :integer then value.to_i
-        when :float then value.to_f
-        else value
-        end
-      end
+    def self.parse(args, &block)
+      new(&block).parse!(args)
     end
 
-    attr_reader :definitions, :values, :remaining_args
-    alias args remaining_args
+    def self.setup(&block)
+      new(&block)
+    end
 
-    def initialize(raw_args = [], &block)
-      @raw_args = raw_args.dup
+    def initialize(&block)
       @definitions = {}
-      @values = {}
-      @remaining_args = []
-      @parsed = false
-
       instance_eval(&block) if block
-      parse! if block
     end
 
-    # DSL: define a toggle flag (default false, presence inverts)
     def flag(name, short: nil, default: false, desc: nil)
       defn = Definition.new(name, short: short, type: :flag, default: default, desc: desc)
       @definitions[name.to_sym] = defn
       self
     end
 
-    # DSL: define an option that takes a value
     def option(name, short: nil, type: :string, default: nil, desc: nil, multi: false)
       defn = Definition.new(name, short: short, type: type, default: default, desc: desc, multi: multi)
       @definitions[name.to_sym] = defn
       self
     end
 
-    def parse!
-      return self if @parsed
+    def parse(args)
+      Args.new(@definitions, args)
+    end
 
-      @definitions.each do |name, defn|
-        @values[name] = defn.multi ? [] : defn.default
-      end
+    def parse!(args)
+      parse(args)
+    end
 
-      args = @raw_args.dup
-      while args.any?
-        arg = args.shift
+    class Args
+      attr_reader :remaining_args, :original_args
+      alias args remaining_args
 
-        if arg == '--'
-          @remaining_args.concat(args)
-          break
-        elsif arg.start_with?('--')
-          parse_long_option(arg, args)
-        elsif arg.start_with?('-') && arg.length > 1
-          parse_short_options(arg, args)
-        else
-          @remaining_args << arg
-        end
+      def initialize(definitions, raw_args)
+        @definitions = definitions
+        @original_args = raw_args.dup.freeze
+        @values = {}
+        @remaining_args = []
+        do_parse(raw_args.dup)
       end
 
-      @parsed = true
-      self
-    end
-
-    def [](name)
-      @values[name.to_sym]
-    end
+      def [](name)
+        @values[name.to_sym]
+      end
 
-    def method_missing(name, *args, &block)
-      name_str = name.to_s
-      if name_str.end_with?('?')
-        key = name_str.chomp('?').to_sym
-        return !!@values[key] if @definitions.key?(key)
-      else
-        return @values[name] if @definitions.key?(name)
+      def fetch(name, default = nil)
+        key = name.to_sym
+        return @values[key] if @values.key?(key)
+        return yield if block_given?
+        default
       end
-      super
-    end
 
-    def respond_to_missing?(name, include_private = false)
-      key = name.to_s.chomp('?').to_sym
-      @definitions.key?(key) || super
-    end
+      def uses_option?(name)
+        key = name.to_sym
+        return false unless @definitions.key?(key)
+        @values[key] != @definitions[key].default
+      end
 
-    def to_h
-      @values.dup
-    end
+      def to_h
+        @values.dup
+      end
 
-    private
+      def method_missing(name, *args, &block)
+        name_str = name.to_s
+        if name_str.end_with?('?')
+          key = name_str.chomp('?').to_sym
+          return !!@values[key] if @definitions.key?(key)
+        else
+          return @values[name] if @definitions.key?(name)
+        end
+        super
+      end
 
-    def parse_long_option(arg, args)
-      if arg.include?('=')
-        opt, value = arg.split('=', 2)
-        name = opt.sub(/^--/, '').tr('-', '_').to_sym
-      else
-        name = arg.sub(/^--/, '').tr('-', '_').to_sym
-        value = nil
+      def respond_to_missing?(name, include_private = false)
+        key = name.to_s.chomp('?').to_sym
+        @definitions.key?(key) || super
       end
 
-      defn = @definitions[name]
-      return unless defn
+      def do_parse(args)
+        @definitions.each do |name, defn|
+          @values[name] = defn.multi ? [] : defn.default
+        end
 
-      if defn.flag?
-        @values[name] = !defn.default
-      else
-        value ||= args.shift
-        store_value(defn, value)
+        while args.any?
+          arg = args.shift
+
+          if arg == '--'
+            @remaining_args.concat(args)
+            break
+          elsif arg.start_with?('--')
+            parse_long_option(arg, args)
+          elsif arg.start_with?('-') && arg.length > 1
+            parse_short_options(arg, args)
+          else
+            @remaining_args << arg
+          end
+        end
       end
-    end
 
-    def parse_short_options(arg, args)
-      chars = arg.sub(/^-/, '').chars
+      def parse_long_option(arg, args)
+        if arg.include?('=')
+          opt, value = arg.split('=', 2)
+          name = opt.sub(/^--/, '').tr('-', '_').to_sym
+        else
+          name = arg.sub(/^--/, '').tr('-', '_').to_sym
+          value = nil
+        end
 
-      chars.each_with_index do |char, idx|
-        defn = @definitions.values.find { |d| d.short == char }
-        next unless defn
+        defn = @definitions[name]
+        return unless defn
 
         if defn.flag?
-          @values[defn.name] = !defn.default
-        elsif idx == chars.length - 1
-          store_value(defn, args.shift)
+          @values[name] = !defn.default
         else
-          store_value(defn, chars[(idx + 1)..].join)
-          break
+          value ||= args.shift
+          store_value(defn, value)
+        end
+      end
+
+      def parse_short_options(arg, args)
+        chars = arg.sub(/^-/, '').chars
+
+        chars.each_with_index do |char, idx|
+          defn = @definitions.values.find { |d| d.short == char }
+          next unless defn
+
+          if defn.flag?
+            @values[defn.name] = !defn.default
+          elsif idx == chars.length - 1
+            store_value(defn, args.shift)
+          else
+            store_value(defn, chars[(idx + 1)..].join)
+            break
+          end
+        end
+      end
+
+      def store_value(defn, value)
+        coerced = defn.coerce(value)
+        if defn.multi
+          @values[defn.name] << coerced
+        else
+          @values[defn.name] = coerced
         end
       end
     end
 
-    def store_value(defn, value)
-      coerced = defn.coerce(value)
-      if defn.multi
-        @values[defn.name] << coerced
-      else
-        @values[defn.name] = coerced
+    class Definition
+      attr_reader :name, :short, :type, :default, :desc, :multi
+
+      def initialize(name, short: nil, type: :string, default: nil, desc: nil, multi: false)
+        @name = name.to_sym
+        @short = short&.to_s
+        @type = type
+        @default = default
+        @desc = desc
+        @multi = multi
+      end
+
+      def flag?
+        type == :flag
+      end
+
+      def long_form
+        "--#{name.to_s.tr('_', '-')}"
+      end
+
+      def short_form
+        short ? "-#{short}" : nil
+      end
+
+      def match?(arg)
+        arg == long_form || arg == short_form
+      end
+
+      def coerce(value)
+        case type
+        when :integer then value.to_i
+        when :float then value.to_f
+        else value
+        end
       end
     end
   end

data/lib/hiiro/version.rb

@@ -1,3 +1,3 @@
 class Hiiro
-  VERSION = "0.1.71"
+  VERSION = "0.1.72"
 end

data/lib/hiiro.rb

@@ -144,8 +144,10 @@ class Hiiro
     runners.add_default(handler, **global_values, **values)
   end
 
-  def add_subcommand(name, **values, &handler)
-    runners.add_subcommand(name, handler, **global_values, **values)
+  def add_subcommand(*names, **values, &handler)
+    names.each do |name|
+      runners.add_subcommand(name, handler, **global_values, **values)
+    end
   end
   alias add_subcmd add_subcommand
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: hiiro
 version: !ruby/object:Gem::Version
-  version: 0.1.71
+  version: 0.1.72
 platform: ruby
 authors:
 - Joshua Toyota
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-02-11 00:00:00.000000000 Z
+date: 2026-02-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: pry