hiiro 0.1.362 → 0.1.363

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a175bf67aa12a51e5cfefdcd556c47466f47d86e633fdb015eab163225db1c21
-  data.tar.gz: adda6458c9cde507d21f49d133171d7d96a2dbb03360d518adaad7e6d74eacf7
+  metadata.gz: f52debf7400300975671eefe3d6bac6766179c179f40cecdafd91d611ae9500b
+  data.tar.gz: 2a5edf1448073cffb3afa07620c92a5e478fd057537f8f16c15d8234697bc28f
 SHA512:
-  metadata.gz: 6db9a4fbf07b07006a1c4ce5a4b03f8dd8f918e64a7fd2055f45c581eae06107552189e5598e1fdc38ed42e40b5bd8962e03c723aaecd41ddc0ef820578a93e2
-  data.tar.gz: 23d2ecee15514029997c3447ce1796a2692e3362dbe52161d3f128bc04d7931623c71dc410cf5e9d7d7ccc1aa706a4cda0c5064814368f107ca1d31e4b9fc859
+  metadata.gz: 22521e0b7c2be0f03b371e5471840eb81e504557b81b0d2a8f45242871160fa1960406d742d79ffc704f3333a3aa606be03519253bc0bf98beca3a9b49fd7ef7
+  data.tar.gz: 6c102bd975d77c9eadaeee63810bc04fefceb09f77b046caa1c7e05486c48928287be23815f9bd36665ad065324724e636e67d3ab0856c36cbd0a5634b7b13d4

data/CHANGELOG.md

@@ -3,10 +3,14 @@
 ## [Unreleased]
 
 ### Added
+- Add the `t` task CLI with `--task`/`-t` selection, durable task status and next actions, document homes, resource references, and Herdr workspace/tab/pane commands.
+- Allow block-only command dispatch with `external_commands: false`, keeping legacy `t-*` executables out of the task CLI.
 - Add `Hiiro::Herdr`, a JSON-backed adapter for Herdr workspaces, tabs, panes, notifications, and command execution.
 - Persist Herdr workspace/tab/pane IDs for invocations, branches, queued prompts, services, and tracked PRs, with read fallbacks for legacy metadata.
 
 ### Changed
+- Keep task command definitions and helpers in `~/bin/t`, using `add_cmd` and native Hiiro help instead of a library-level TaskCLI and custom help template.
+- Preserve task records and resource references when detaching or pruning worktrees.
 - Move task, project, queue, service, background, Claude, app navigation, PR attach, title, and notification workflows from tmux to Herdr.
 - Keep `h session` and `h window` as compatibility commands for Herdr workspaces and tabs.
 
@@ -15,6 +19,10 @@
 - Remove the old `Hiiro::Tmux` adapter and tmux-specific command tests.
 
 ### Fixed
+- Preserve `add_cmd` declaration locations and argument metadata in generated help; allow command groups to pass arguments and help through to child commands.
+- Make undeclared `add_cmd opts:` entries boolean flags without consuming positional arguments; preserve explicit options and reserve conflicting short aliases.
+- Show selected command options for `add_cmd -h`/`--help` without executing the command block.
+- Focus the exact Herdr pane through the socket API and read the CLI's plain-text pane output without JSON parsing.
 - Restore the missing `Hiiro::Bins` helper so `require "hiiro"` boots and commands like `h jumplist record` dispatch correctly.
 - Make Hiiro's Ruby requirement explicit as Ruby 3.2+ and have rbenv-wide gem installs skip incompatible Ruby versions.
 - Update the publish script to preserve the Ruby support constant, run only on supported Ruby, and install releases only into compatible rbenv versions.

data/README.md

@@ -59,6 +59,23 @@ h ping
 # => pong
 ```
 
+### Task CLI
+
+`~/bin/t` contains the task commands and helpers, using Hiiro's `add_cmd` DSL
+and existing task records. `t new NAME` creates a task and its notes directory
+without creating a Git worktree. Select a task with `--task NAME` or `-t NAME`.
+Root and group help are generated by Hiiro; leaf command help lists its selected options.
+
+```sh
+t new investigation
+t next -t investigation "Inspect the failing request"
+t doc new findings -t investigation
+t doc open findings -t investigation
+t show investigation
+```
+
+See [Task commands](docs/h-task.md) for the full command reference.
+
 ## Subcommands
 
 ### Base Commands
@@ -181,6 +198,44 @@ add_subcmd(:pwd) do |*args|
 end
 ```
 
+### Commands with declared options
+
+Use `add_cmd` to expose a command's options in help. Undeclared names in `opts:`
+become boolean flags with a default of `false`. A flag does not consume the next
+positional argument.
+
+```ruby
+Hiiro.run do
+  add_option :task, short: :t, desc: 'Task name'
+
+  add_cmd :test, opts: %i[a b c d task] do
+    puts 'a was set' if opts.a
+    puts opts.task if opts.task
+    puts opts.args
+  end
+end
+```
+
+Here, `test -a payload -t investigation` sets `opts.a` to `true`, leaves
+`payload` in `opts.args`, and sets `opts.task` to `investigation`.
+`test -h` and `test --help` display the selected options without running the
+command block.
+
+Automatic flags use their first letter as a short alias only when it is unique
+among the command's automatic flags and does not conflict with a selected
+explicit option or `-h`. Every automatic flag has a long form. Explicit flags
+and value options keep their definitions.
+
+For a command that delegates to `make_child`, use `add_cmd(..., passthrough: true)`.
+It forwards control without parsing the parent's arguments or intercepting the
+child's `--help`. The child declares and parses its own options. Generated help
+uses the original command block's source location and declared `args:`, not the
+internal wrapper's signature.
+
+For a CLI that should dispatch only registered blocks, pass
+`external_commands: false` to `Hiiro.run` and its `make_child` calls. This
+prevents unrelated same-prefix executables on `PATH` from taking precedence.
+
 ## Writing Plugins
 
 Plugins are Ruby modules that extend Hiiro instances:

data/docs/h-task.md

@@ -1,8 +1,111 @@
-# h task
+# Task commands
 
-Manage top-level tasks. Each task pairs a worktree with a Herdr workspace. `h task start` creates worktrees under Hiiro's default work root; `h task from` can register an existing worktree from any repo or path.
+`t` manages durable tasks. A task can be a coding project, an investigation, or administrative work. It does not need Git or Herdr.
 
-Tasks are stored in `~/.config/hiiro/tasks/tasks.yml` (SQLite-backed with YAML backup).
+Task records and resource references live in `~/.config/hiiro/hiiro.db`, in the existing `tasks` table and the `task_resources` table. `h task` uses the same records. Its YAML file is a backup, not a separate task store.
+
+## t
+
+The command implementation lives in `~/bin/t`, not a `Hiiro::TaskCLI` library class. Commands use `add_cmd` with per-command argument and option declarations. Running `t` or `t doc` displays Hiiro's generated subcommand table, including declaration locations. Leaf help, such as `t directory add --help`, displays only that command's options without executing it. There is no separate task help template. `t` does not run `h task` or discover legacy `t-*` executables.
+
+Every task command accepts `-t TASK` or `--task TASK` before or after the command. Explicit task names are exact and take precedence over the current directory or workspace. Conflicting explicit names are errors.
+
+Without a selector, `t` considers the current directory inside a task home, an attached directory, or a legacy worktree. In a Herdr terminal, it also queries the current workspace. If the contexts identify different tasks, the command fails without changing task data. A shared directory therefore requires an explicit selector. Outside Herdr, an unrelated focused workspace does not affect task selection.
+
+### Task records
+
+```text
+t list [--all]
+t show [TASK]
+t current
+t new TASK
+t next [TEXT...] [--clear]
+t status [active|waiting|done|archived]
+t waiting [TEXT...] [--clear]
+t done
+t archive
+```
+
+`list` shows active and waiting tasks. `--all` includes completed and archived tasks. `next`, `waiting`, and `status` without arguments display the current value.
+
+`new TASK` creates a record and `~/notes/work/TASK`. It never creates a Git worktree, moves code, or launches Herdr. Repeating `new` keeps the existing record and ensures its home exists. Names contain 1-120 ASCII letters, digits, dots, underscores, or hyphens and start with a letter or digit. Existing names that contain other characters remain usable, with those characters percent-encoded in the computed home directory name.
+
+Setting waiting text changes status to `waiting`. Clearing that text changes a waiting task back to `active`. `done` and `archive` change status and record timestamps. They never remove a task home, a file, a directory, a link, or a workspace. `status active` reopens a task.
+
+```bash
+t new audit-invoices
+t next -t audit-invoices 'Compare the September export'
+t waiting -t audit-invoices 'Finance approval'
+t waiting -t audit-invoices --clear
+t done -t audit-invoices
+t show audit-invoices
+```
+
+### Directory, link, PR, and file references
+
+```text
+t directory add PATH [--primary] [--label LABEL]
+t directory list
+t directory open [ID|PATH|LABEL]
+t link add URL [--kind general|issue|thread] [--label LABEL]
+t link list [--kind general|issue|thread]
+t link open [ID|URL|LABEL]
+t pr add URL [--label LABEL]
+t pr list
+t pr open [ID|URL|LABEL]
+t file add PATH [--label LABEL]
+t file list
+t file open [ID|PATH|LABEL]
+```
+
+Directory and file attachments must already exist. `add` stores their canonical paths without moving or copying anything. Repeating an identical attachment does not create another reference. `--primary` marks an attached directory as the default code directory for new workspace tabs and panes.
+
+Links must be absolute HTTP or HTTPS URLs. `link list` includes PR references unless a kind filter is present. PRs use the same resource storage as other links and do not require a Git repository or provider API.
+
+`file list` also discovers files in the task home, including documents, without registration. Home files can be opened by a relative path or an unambiguous basename. An omitted open selector works only when exactly one resource matches. Otherwise, the command requires an ID, path, URL, or unique label.
+
+`open` uses the operating system's default application. Attachments remain references even after task completion.
+
+### Documents
+
+```text
+t doc new NAME [TITLE...]
+t doc list
+t doc open [NAME]
+```
+
+`doc new` creates a Markdown file in the task home with an initial heading. It never overwrites an existing file. Documents have a stable task-ID prefix, such as `task-42-investigation.md`, to avoid collisions in `mdoc`'s shared HTML output directory. `doc open investigation` accepts the short name and invokes `mdoc`. Existing Markdown files in the task home also appear without registration.
+
+Task creation, metadata, references, and document creation/listing work without Git or Herdr. Document reading requires `mdoc` on `PATH` and its existing configuration.
+
+### Herdr workspaces, tabs, and panes
+
+```text
+t workspace open [--directory PATH]
+t workspace show
+t tab list
+t tab new [LABEL] [--directory PATH] [--command COMMAND]
+t tab open ID|LABEL
+t pane list
+t pane open ID|LABEL
+t pane read ID|LABEL
+t pane run ID|LABEL COMMAND...
+t pane split ID|LABEL [--direction right|down] [--directory PATH] [--command COMMAND]
+```
+
+These commands require a running Herdr server. `workspace open` focuses the workspace with the task's label or creates one. A new workspace starts in the explicit directory, the primary code directory, the legacy worktree, or the task home, in that order. `--directory` changes that operation's start directory without changing stored attachments.
+
+`workspace show` queries the current tabs and panes. Tab and pane selectors must belong to the selected task's workspace. Duplicate labels require a live ID. No pane or tab ID is stored as durable task identity. Task workspace labels follow Herdr's dot-to-underscore normalization. Colliding task or workspace labels are errors rather than fuzzy matches.
+
+Use `--` before literal command arguments that begin with a dash:
+
+```bash
+t pane run -t audit-invoices PANE_ID -- printf '%s\n' --example
+```
+
+## h task
+
+The existing `h task` commands below retain their coding-worktree operations. Unlike `t new`, `h task start` can create a worktree for a new task. For a task without a worktree, path resolution uses its task home. Starting an existing noncoding task switches to that home without creating a worktree.
 
 ## Synopsis
 
@@ -225,19 +328,19 @@ h task path -a feat bug        # tasks whose name starts with "feat" or "bug"
 
 ### prune
 
-Drop task records whose worktree directory is missing on disk. Useful after deleting worktrees out-of-band (e.g. `git worktree remove` on stale branches). Defaults to a dry-run; pass `-f` to actually remove.
+Detach worktree associations whose directories are missing. The task record, metadata, and resource references remain. Tasks without worktrees are not pruned. Defaults to a dry-run.
 
 **Options**
 
 | Flag | Short | Description | Default |
 |------|-------|-------------|---------|
-| `--force` | `-f` | Actually delete (default is dry-run) | false |
+| `--force` | `-f` | Detach missing worktrees | false |
 
 **Examples**
 
 ```bash
 h task prune        # show what would be pruned
-h task prune -f     # actually remove the missing-worktree task records
+h task prune -f     # detach missing worktrees, retaining task records
 ```
 
 ---
@@ -264,7 +367,7 @@ h task queue hadd
 
 ### resume
 
-Re-register an available (unassigned) worktree as a new task and switch to it. With no argument, opens a fuzzyfind selector over available worktrees.
+Associate an available worktree with a new task or an existing task whose worktree was detached, then switch to it. Existing task metadata is preserved. With no argument, opens a fuzzyfind selector over available worktrees.
 
 **Examples**
 
@@ -438,7 +541,7 @@ h task st
 
 ### stop
 
-Remove a task from the task list (preserves the worktree for future reuse via `resume`). With no arguments, opens a fuzzyfind selector.
+Detach a task's worktree association and those of its subtasks. The task records, metadata, workspace labels, and resources remain. The former worktree path becomes a directory reference, and the worktree is available for reuse through `resume`. With no arguments, opens a fuzzyfind selector.
 
 **Examples**
 

data/lib/hiiro/herdr.rb

@@ -1,4 +1,6 @@
 require 'json'
+require 'socket'
+require 'timeout'
 
 class Hiiro
   class Herdr
@@ -487,11 +489,20 @@ class Hiiro
     alias kill_pane close_pane
 
     def focus_pane(ref)
-      pane = get_pane(ref)
-      return false unless pane
-
-      focus_workspace(pane.workspace_id)
-      focus_tab(pane.tab_id)
+      status = @executor.capture('herdr', 'status', 'server')
+      socket_path = status.lines.find { |line| line.start_with?('socket: ') }&.delete_prefix('socket: ')&.strip
+      return false unless socket_path
+
+      request = { id: 'hiiro:pane:focus', method: 'pane.focus', params: { pane_id: ref } }
+      Timeout.timeout(5) do
+        UNIXSocket.open(socket_path) do |socket|
+          socket.puts(JSON.generate(request))
+          response = JSON.parse(socket.gets || '{}')
+          response.dig('result', 'pane', 'focused') == true
+        end
+      end
+    rescue SystemCallError, IOError, JSON::ParserError, Timeout::Error
+      false
     end
     alias select_pane focus_pane
 
@@ -546,7 +557,7 @@ class Hiiro
 
       args = ['pane', 'read', pane_id, '--source', source]
       args += ['--lines', lines.to_s] if lines
-      capture_result(*args).dig('read', 'text')
+      @executor.capture('herdr', *args)
     end
     alias capture_pane read_pane
 

data/lib/hiiro/options.rb

@@ -86,13 +86,18 @@ class Hiiro
     public
 
     def select(names)
+      names = names.map(&:to_sym).uniq
       subset = self.class.setup {}
+      reserved_shorts = ['h'] + names.filter_map { |name| @definitions[name]&.short }
+      auto_shorts = names.reject { |name| @definitions.key?(name) }.map { |name| name.to_s[0] }.tally
       names.each do |name|
-        defn = @definitions[name.to_sym]
+        defn = @definitions[name]
         if defn
-          subset.definitions[name.to_sym] = defn
+          subset.definitions[name] = defn
         else
-          subset.definitions[name.to_sym] = Definition.new(name, short: name.to_s.chars.first, desc: "auto-created flag: #{name}")
+          short = name.to_s[0]
+          short = nil if reserved_shorts.include?(short) || auto_shorts[short] > 1
+          subset.flag(name, short: short, desc: "auto-created flag: #{name}")
         end
       end
       subset

data/lib/hiiro/task_record.rb

@@ -1,9 +1,13 @@
 require 'sequel'
+require 'uri'
 
 class Hiiro
   class TaskRecord < Sequel::Model(:tasks)
     Hiiro::DB.register(self)
 
+    METADATA_COLUMNS = %i[status next_action waiting_on primary_directory updated_at completed_at archived_at].freeze
+    STATUSES = %w[active waiting done archived].freeze
+
     def self.create_table!(db)
       db.create_table?(:tasks) do
         primary_key :id
@@ -17,6 +21,37 @@ class Hiiro
       end
     end
 
+
+    def self.migrate!(db)
+      columns = db.schema(:tasks).map(&:first)
+      METADATA_COLUMNS.each do |column|
+        db.alter_table(:tasks) { add_column column, String } unless columns.include?(column)
+      end
+    end
+
+    def self.home_for(name)
+      component = URI::DEFAULT_PARSER.escape(name.to_s, /[^A-Za-z0-9._-]/)
+      component = component.gsub('.', '%2E') if %w[. ..].include?(component)
+      raise ArgumentError, 'Task name cannot be empty' if component.empty?
+
+      File.join(Dir.home, 'notes', 'work', component)
+    end
+
+    def home
+      self.class.home_for(name)
+    end
+
+    def task_status
+      status || 'active'
+    end
+
+    def task_attributes
+      values.reject { |key, _| key == :id }.compact
+    end
+
+    def resources
+      TaskResource.where(task_id: id).order(:id)
+    end
     def self.top_level
       where(Sequel.~(Sequel.like(:name, '%/%')))
     end
@@ -34,4 +69,20 @@ class Hiiro
       order(:name).all
     end
   end
+
+  class TaskResource < Sequel::Model(:task_resources)
+    Hiiro::DB.register(self)
+
+    def self.create_table!(db)
+      db.create_table?(:task_resources) do
+        primary_key :id
+        foreign_key :task_id, :tasks, null: false, on_delete: :cascade
+        String :kind, null: false
+        String :target, null: false
+        String :label
+        String :created_at
+        unique [:task_id, :kind, :target]
+      end
+    end
+  end
 end

data/lib/hiiro/tasks.rb

@@ -89,6 +89,7 @@ class Hiiro
       return nil unless target
 
       return target.path if target.is_a?(FallbackTarget)
+      return target.home unless target.tree_name
 
       tree = environment.find_tree(target.tree_name)
       return tree.path if tree
@@ -250,8 +251,8 @@ class Hiiro
         return
       end
 
-      config.remove_task(task.name)
-      subtasks(task).each { |st| config.remove_task(st.name) }
+      config.detach_tree(task.name)
+      subtasks(task).each { |st| config.detach_tree(st.name) }
 
       puts "Stopped task '#{task.name}' (worktree available for reuse)"
     end
@@ -265,12 +266,14 @@ class Hiiro
       # Derive a default task name from the tree name: "foo/main" -> "foo"
       task_name ||= tree.name.end_with?('/main') ? tree.name.chomp('/main') : tree.name
 
-      if task_by_name(task_name)
-        puts "Task '#{task_name}' already exists"
+      existing = task_by_name(task_name)
+      if existing&.tree_name
+        puts "Task '#{task_name}' already has a worktree"
         return
       end
 
-      task = Task.new(name: task_name, tree: tree.name, session: task_name)
+      attributes = existing ? existing.to_h : { name: task_name }
+      task = Task.new(**attributes.merge(tree: tree.name, session: task_name))
       config.save_task(task)
       puts "Resumed task '#{task_name}' from worktree '#{tree.name}'"
 
@@ -706,27 +709,26 @@ class Hiiro
       end
 
       def save_task(task)
-        TaskRecord.find_or_create(name: task.name) do |r|
-          r.tree = task.tree_name
-          r.session = task.session_name
-          r.app = task.respond_to?(:app) ? task.app : nil
-          r.color_index = task.color_index
-        end.update(
-          tree: task.tree_name,
-          session: task.session_name,
-          app: task.respond_to?(:app) ? task.app : nil,
-          color_index: task.color_index
-        )
+        record = TaskRecord.find_by_name(task.name) || TaskRecord.new(name: task.name, created_at: Time.now.iso8601)
+        record.set(task.to_h.merge(tree: task.tree_name, session: task.session_name, color_index: task.color_index))
+        record.save
         save_tasks_yaml_backup
       rescue => e
         warn "Failed to save task to DB: #{e}"
       end
 
-      def remove_task(name)
-        TaskRecord.where(name: name).delete
+      def detach_tree(name)
+        record = TaskRecord.find_by_name(name)
+        return unless record&.tree
+
+        path = record.tree.start_with?('/') ? record.tree : File.join(Hiiro::WORK_DIR, record.tree)
+        Hiiro::DB.connection.transaction do
+          TaskResource.find_or_create(task_id: record.id, kind: 'directory', target: path)
+          record.update(tree: nil, updated_at: Time.now.iso8601)
+        end
         save_tasks_yaml_backup
       rescue => e
-        warn "Failed to remove task from DB: #{e}"
+        warn "Failed to detach task worktree: #{e}"
       end
 
       private
@@ -735,7 +737,7 @@ class Hiiro
         rows = TaskRecord.all_as_list
         return fallback_load_tasks_from_yaml if rows.empty?
         { 'tasks' => rows.map { |r|
-          { 'name' => r.name, 'tree' => r.tree, 'session' => r.session, 'app' => r.app, 'color_index' => r.color_index }.compact
+          r.task_attributes.transform_keys(&:to_s)
         }}
       rescue => e
         warn "Failed to load tasks from DB: #{e}. Falling back to YAML."
@@ -801,7 +803,7 @@ class Hiiro
 
       def save_tasks_yaml_backup(data = nil)
         data ||= { 'tasks' => TaskRecord.all_as_list.map { |r|
-          { 'name' => r.name, 'tree' => r.tree, 'session' => r.session, 'app' => r.app, 'color_index' => r.color_index }.compact
+          r.task_attributes.transform_keys(&:to_s)
         }}
         FileUtils.mkdir_p(File.dirname(tasks_file))
         File.write(tasks_file, YAML.dump(data))
@@ -1213,33 +1215,33 @@ class Hiiro
 
         h.add_subcmd(:prune) do |*raw_args|
           opts = Hiiro::Options.parse(raw_args) {
-            flag(:force, short: :f, desc: 'Actually delete (default is dry-run)')
+            flag(:force, short: :f, desc: 'Detach missing worktrees (default is dry-run)')
           }
 
           to_remove = tm.environment.all_tasks.select do |task|
-            next true unless task.tree_name
+            next false unless task.tree_name
             path = tm.resolve_path(task)
             path.nil? || !Dir.exist?(path)
           end
 
           if to_remove.empty?
-            puts "No tasks to prune"
+            puts "No missing task worktrees"
             next
           end
 
           to_remove.each do |task|
             path = task.tree_name ? tm.resolve_path(task) : '(no tree)'
             if opts.force
-              tm.config.remove_task(task.name)
-              puts "Pruned: #{task.name} (#{path})"
+              tm.config.detach_tree(task.name)
+              puts "Detached missing worktree: #{task.name} (#{path}); task retained"
             else
-              puts "Would prune: #{task.name} (#{path})"
+              puts "Would detach missing worktree: #{task.name} (#{path})"
             end
           end
 
           unless opts.force
             puts
-            puts "Re-run with -f to actually delete."
+            puts "Re-run with -f to detach these worktree references."
           end
         end
 
@@ -1486,13 +1488,19 @@ class Hiiro
   end
 
   class Task
-    attr_reader :name, :tree_name, :session_name, :color_index
+    attr_reader :name, :tree_name, :session_name, :color_index, :app, :created_at, *TaskRecord::METADATA_COLUMNS
 
-    def initialize(name:, tree: nil, session: nil, color_index: nil, **_)
+    def initialize(name:, tree: nil, session: nil, color_index: nil, **attributes)
       @name = name
       @tree_name = tree
       @session_name = session || name
       @color_index = color_index
+      @attributes = attributes.slice(:app, :created_at, *TaskRecord::METADATA_COLUMNS)
+      @attributes.each { |key, value| instance_variable_set("@#{key}", value) }
+    end
+
+    def home
+      TaskRecord.home_for(name)
     end
 
     def parent_name
@@ -1537,7 +1545,7 @@ class Hiiro
     end
 
     def to_h
-      h = { name: name }
+      h = @attributes.merge(name: name)
       h[:tree] = tree_name if tree_name
       h[:session] = session_name if session_name != name
       h[:color_index] = color_index unless color_index.nil?

data/lib/hiiro/version.rb

@@ -1,4 +1,4 @@
 class Hiiro
-  VERSION = "0.1.362"
+  VERSION = "0.1.363"
   SUPPORTED_RUBY_VERSION = ">= 3.2.0"
 end

data/lib/hiiro.rb

@@ -355,11 +355,16 @@ class Hiiro
     end
   end
 
-  def add_cmd(*names, args: [], opts: [], &block)
+  def add_cmd(*names, args: [], opts: [], passthrough: false, &block)
     cmd_opts = options.select(opts)
 
     wrapper = lambda do |*raw_args|
+      next instance_eval(&block) if passthrough
       @opts = cmd_opts.parse(raw_args)
+      if @opts.help?
+        puts @opts.help_text
+        next
+      end
       instance_eval(&block)
     end
 
@@ -368,7 +373,8 @@ class Hiiro
         name, wrapper,
         subcmd_args: args,
         subcmd_opts: cmd_opts,
-        **global_values
+        **global_values,
+        source_location: block.source_location&.join(':')
       )
     end
   end
@@ -605,6 +611,8 @@ class Hiiro
     end
 
     def all_bins
+      return [] unless hiiro.global_values.fetch(:external_commands, true)
+
       pattern = format('{%s}/%s-*', paths.join(?,), bin_name)
 
       Dir.glob(pattern).map { |path| Bin.new(bin_name, path) }
@@ -740,13 +748,14 @@ class Hiiro
       end
 
       def location
-        handler.source_location&.join(':')
+        values[:source_location] || handler.source_location&.join(':')
       end
 
       def params_string
         if subcmd_args.any?
           return subcmd_args.map { |a| "<#{a}>" }.join(' ')
         end
+        return nil if subcmd_opts
 
         return nil unless handler.respond_to?(:parameters)
 

metadata

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