hiiro 0.1.352 → 0.1.354

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 16ba8062d4d8f261771beb98b5baad695b43d05f6f0be4f8ebcc0f8e18a6e89b
-  data.tar.gz: b756598368c4faa85ec332df703e4f2e859f84bcdf2c68319dc1b5ce48c6d7ab
+  metadata.gz: 9a368e5a5a2c932aa609faa46c699b3a112e835908fe7788cdab234f583a92ee
+  data.tar.gz: 2153cf58429b63859d220615d9a5404fa14e1388ce735bc385d399c2856ca204
 SHA512:
-  metadata.gz: 417c7bc005bbe71d9fc62a9cab04616c78005aad16f9604eb98f5aee6cfbe42a19bbbf789f04fb0a452c3ebea7e323155a7432d380f03f6b42cb0be3d4b66260
-  data.tar.gz: 2b0b553966be3f3cfd4d457afa62b7c8021b9633d5eaa92ded65ad808d41256de9216ab495c474fcbad27c3a479f3ff530ad69fe4c6f91457d06f4db213946b6
+  metadata.gz: 422c65b26c19e47db3a28eb5643f9b525ba862dbfcdab1d75ada76f43b1c3add1bc70ce97183d4934a06403fc6bb4fa244b8821127c0a0e6ec8b9778e8e022a0
+  data.tar.gz: 1b005ce7ebb9acec393d6587d939ef1623c5d69a1d8869bf9540ca1e4e4095008bc4d6a3f0fa76bbcac6ac7849059b8166ae2e6fb08073ed31d48d186356459f

data/CHANGELOG.md

@@ -2,6 +2,15 @@
 
 ## [Unreleased]
 
+### Added
+- `h task from <worktree-path> <task-name>` registers an existing git worktree from any path as a Hiiro task and switches to it.
+
+## [0.1.353] - 2026-04-26
+
+### Added
+- `Hiiro::Tui::ListScreen` for building keyboard-driven full-screen list interfaces
+- `Hiiro::Config.load_yaml` and `Hiiro::Config.yaml_dig` helpers for YAML file loading with nested key access
+
 ## [0.1.352] - 2026-04-24
 
 ### Added

data/CLAUDE.md

@@ -2,6 +2,10 @@
 
 This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
 
+## Safety
+
+- NEVER commit secrets, tokens, api keys, etc. do not include any work-related content or information
+
 ## Project Overview
 
 Hiiro is a lightweight CLI framework for Ruby that enables building multi-command tools similar to `git` or `docker`. It provides subcommand dispatch, abbreviation matching (e.g., `h ex hel` matches `h example hello`), and a plugin system.
@@ -546,4 +550,3 @@ All config lives in `~/.config/hiiro/`:
 - lib/hiiro/tmux.rb
 - lib/hiiro/tmux/*
 
-

data/README.md

@@ -8,6 +8,7 @@ A lightweight, extensible CLI framework for Ruby. Build your own multi-command t
 - **Abbreviation matching** - Type `h ex hel` instead of `h example hello`
 - **Plugin system** - Extend functionality with reusable modules
 - **Per-command storage** - Each command gets its own pin/config namespace
+- **TUI helpers** - Build keyboard-driven list screens with `Hiiro::Tui::ListScreen`
 
 See [docs/](docs/) for detailed documentation on all subcommands.
 
@@ -64,7 +65,7 @@ h ping
 | `h setup` | Install plugins and subcommands to system paths |
 | `h edit` | Open the h script in your editor |
 | `h alert` | macOS desktop notifications via terminal-notifier |
-| `h task` | Task management across git worktrees (via Tasks plugin) |
+| `h task` | Task management across git worktrees, including existing external worktrees (via Tasks plugin) |
 | `h subtask` | Subtask management within tasks (via Tasks plugin) |
 
 ### External Subcommands
@@ -115,7 +116,7 @@ Plugins are Ruby modules loaded from `~/.config/hiiro/plugins/`:
 |--------|-------------|
 | Pins | Per-command YAML key-value storage |
 | Project | Project directory navigation with tmux session management |
-| Tasks | Task lifecycle management across git worktrees with subtask support |
+| Tasks | Task lifecycle management across git worktrees with external-worktree registration and subtask support |
 | Notify | macOS desktop notifications via terminal-notifier |
 
 ## Adding Subcommands
@@ -154,6 +155,10 @@ h example hello  # => Hi!
 h example bye    # => Goodbye!
 ```
 
+### Building TUIs
+
+Use `Hiiro::Tui::ListScreen` for simple full-screen list interfaces. Subclass it, override `header_lines`, `format_row`, and `handle_key`, then run it from a normal `Hiiro.run` subcommand.
+
 ### Method 2: Inline Subcommands
 
 Modify `exe/h` directly to add subcommands to the base `h` command:

data/docs/h-task.md

@@ -1,6 +1,6 @@
 # h task
 
-Manage top-level tasks. Each task is a worktree + tmux session pair. Tasks enable parallel development across multiple features — each with an isolated checkout and its own tmux session.
+Manage top-level tasks. Each task is a worktree + tmux session pair. Tasks enable parallel development across multiple features — each with an isolated checkout and its own tmux session. `h task start` creates worktrees under Hiiro's default work root; `h task from` can register an existing worktree from any repo/path.
 
 Tasks are stored in `~/.config/hiiro/tasks/tasks.yml` (SQLite-backed with YAML backup).
 
@@ -164,6 +164,30 @@ h task file add myapp path/to/file.rb
 
 ---
 
+### from
+
+Register an existing git worktree as a Hiiro task and switch to it. The path is normalized to the worktree root with `git rev-parse --show-toplevel`, then stored as the task's tree path.
+
+**Examples**
+
+```bash
+h task from ~/ic_repos/other_repo_base_dir other-task
+h task path other-task
+h task switch other-task
+```
+
+Stored task shape:
+
+```js
+{
+  name: "other-task",
+  tree: "/Users/josh/ic_repos/other_repo_base_dir",
+  session: "other-task"
+}
+```
+
+---
+
 ### ls / list
 
 List all tasks with their worktree, branch, and session. Also shows available (unassigned) worktrees and extra tmux sessions.
@@ -548,4 +572,3 @@ h task untag my-feature          # remove all tags
 List worktrees for the current task. Delegates to `h wtree`.
 
 ---
-

data/docs/h.md

@@ -30,7 +30,7 @@ These subcommands are defined directly in `exe/h` or loaded from `lib/`:
 | [`h service`](h-service.md) | Dev service management with tmux, env files, and service groups | `lib/hiiro/service_manager.rb` |
 | `h setup` | Install plugins and bin scripts to `~/bin` | `exe/h` |
 | [`h subtask`](h-subtask.md) | Subtask management scoped to the current parent task | `lib/hiiro/tasks.rb` |
-| [`h task`](h-task.md) | Task management — worktree + tmux session pairs for parallel development | `lib/hiiro/tasks.rb` |
+| [`h task`](h-task.md) | Task management — worktree + tmux session pairs, including existing external worktrees | `lib/hiiro/tasks.rb` |
 | `h version` | Print installed hiiro version (`-a` for all rbenv versions) | `exe/h` |
 
 ## External subcommands

data/lib/hiiro/config.rb

@@ -1,3 +1,5 @@
+require 'yaml'
+
 class Hiiro
   class Config
     BASE_DIR = File.join(Dir.home, '.config/hiiro')
@@ -15,6 +17,36 @@ class Hiiro
         File.join(BASE_DIR, relpath)
       end
 
+      def load_yaml(relpath = 'config.yml', default: {}, permitted_classes: [Symbol])
+        file = path(relpath)
+        return default unless File.exist?(file)
+
+        YAML.safe_load_file(file, permitted_classes: permitted_classes) || default
+      rescue StandardError
+        default
+      end
+
+      def yaml_dig(relpath = 'config.yml', *keys, default: nil, permitted_classes: [Symbol])
+        value = load_yaml(relpath, default: {}, permitted_classes: permitted_classes)
+
+        keys.flatten.each do |key|
+          return default unless value.is_a?(Hash)
+
+          value =
+            if value.key?(key)
+              value[key]
+            elsif value.key?(key.to_s)
+              value[key.to_s]
+            elsif key.respond_to?(:to_sym) && value.key?(key.to_sym)
+              value[key.to_sym]
+            else
+              return default
+            end
+        end
+
+        value.nil? ? default : value
+      end
+
       def data_path(relpath='')
         File.join(DATA_DIR, relpath)
       end

data/lib/hiiro/tasks.rb

@@ -91,7 +91,10 @@ class Hiiro
       return target.path if target.is_a?(FallbackTarget)
 
       tree = environment.find_tree(target.tree_name)
-      tree ? tree.path : File.join(Hiiro::WORK_DIR, target.tree_name)
+      return tree.path if tree
+      return target.tree_name if target.absolute_tree?
+
+      File.join(Hiiro::WORK_DIR, target.tree_name)
     end
 
     def task_by_tree(tree_name)
@@ -116,6 +119,43 @@ class Hiiro
 
     # --- Actions ---
 
+    def task_from_worktree(path, name)
+      if path.nil? || name.nil? || name.empty?
+        puts "Usage: h #{scope} from <worktree-path> <task-name>"
+        return
+      end
+
+      root = git_worktree_root(path)
+      unless root
+        puts "ERROR: '#{path}' is not inside a git worktree"
+        return
+      end
+
+      existing = task_by_name(name)
+      if existing
+        existing_path = resolve_path(existing)
+        if same_path?(existing_path, root)
+          puts "Task '#{existing.name}' already uses '#{root}'. Switching..."
+          return existing
+        end
+
+        puts "ERROR: Task '#{existing.name}' already exists for '#{existing_path}'"
+        return
+      end
+
+      existing_for_path = environment.all_tasks.find { |task| same_path?(resolve_path(task), root) }
+      if existing_for_path
+        puts "Worktree '#{root}' is already registered as task '#{existing_for_path.name}'. Switching..."
+        return existing_for_path
+      end
+
+      color_index = Hiiro::TaskColors.next_index(config.tasks.map(&:color_index).compact)
+      task = Task.new(name: name, tree: root, session: name, color_index: color_index)
+      config.save_task(task)
+      puts "Added task '#{name}' from worktree '#{root}'"
+      task
+    end
+
     def start_task(name, app_name: nil, sparse_groups: [])
       existing = task_by_name(name)
       if existing
@@ -185,8 +225,7 @@ class Hiiro
         return
       end
 
-      tree = environment.find_tree(task.tree_name)
-      tree_path = tree ? tree.path : File.join(Hiiro::WORK_DIR, task.tree_name)
+      tree_path = resolve_path(task)
 
       session_name = task.session_name
       session_exists = system('tmux', 'has-session', '-t', "=#{session_name}", err: File::NULL)
@@ -369,8 +408,7 @@ class Hiiro
 
       puts "Task: #{task.name}"
       puts "Worktree: #{task.tree_name}"
-      tree = environment.find_tree(task.tree_name)
-      puts "Path: #{tree&.path || '(unknown)'}"
+      puts "Path: #{resolve_path(task) || '(unknown)'}"
       puts "Session: #{task.session_name}"
       puts "Parent: #{task.parent_name}" if task.subtask?
     end
@@ -445,9 +483,7 @@ class Hiiro
         return
       end
 
-      tree = environment.find_tree(task.tree_name)
-      path = tree ? tree.path : File.join(Hiiro::WORK_DIR, task.tree_name)
-      send_cd(path)
+      send_cd(resolve_path(task))
     end
 
     def cd_to_app(app_name = nil)
@@ -458,8 +494,7 @@ class Hiiro
       end
 
       if app_name.nil? || app_name.empty?
-        tree = environment.find_tree(task.tree_name)
-        send_cd(tree&.path || File.join(Hiiro::WORK_DIR, task.tree_name))
+        send_cd(resolve_path(task))
         return
       end
 
@@ -473,8 +508,7 @@ class Hiiro
     def app_path(app_name = nil)
       task = current_task
       tree_root = if task
-        tree = environment.find_tree(task.tree_name)
-        tree&.path || File.join(Hiiro::WORK_DIR, task.tree_name)
+        resolve_path(task)
       else
         Hiiro::Git.new(nil, Dir.pwd).root
       end
@@ -596,14 +630,31 @@ class Hiiro
       end
     end
 
+    def git_worktree_root(path)
+      expanded = File.expand_path(path.to_s)
+      return nil unless Dir.exist?(expanded)
+
+      root = IO.popen(['git', '-C', expanded, 'rev-parse', '--show-toplevel'], err: File::NULL, &:read).to_s.strip
+      return nil if root.empty?
+
+      File.expand_path(root)
+    rescue
+      nil
+    end
+
+    def same_path?(left, right)
+      return false if left.nil? || right.nil?
+
+      File.expand_path(left) == File.expand_path(right)
+    end
+
     def find_available_tree
       assigned_tree_names = environment.all_tasks.map(&:tree_name)
       environment.all_trees.find { |tree| !assigned_tree_names.include?(tree.name) }
     end
 
     def resolve_app(app_name, task)
-      tree = environment.find_tree(task.tree_name)
-      tree_root = tree ? tree.path : File.join(Hiiro::WORK_DIR, task.tree_name)
+      tree_root = resolve_path(task)
 
       result = environment.app_matcher.find_all(app_name)
 
@@ -1036,6 +1087,13 @@ class Hiiro
 
         h.add_subcmd(:apps) { tm.list_apps }
 
+        if tm.scope == :task
+          h.add_subcmd(:from) do |path = nil, task_name = nil|
+            task = tm.task_from_worktree(path, task_name)
+            tm.switch_to_task(task) if task
+          end
+        end
+
         h.add_subcmd(:cd) do |*raw_args|
           opts = Hiiro::Options.parse(raw_args, &task_opts_block)
           task, positional = resolve_task.call(opts, opts.args)
@@ -1419,6 +1477,13 @@ class Hiiro
   class Tree
     attr_reader :path, :head, :branch
 
+    def self.from_path(path)
+      expanded = File.expand_path(path.to_s)
+      branch = Hiiro::Git.new(nil, expanded).branch if Dir.exist?(expanded)
+      branch = nil if branch.nil? || branch.empty? || branch == 'HEAD'
+      new(path: expanded, branch: branch)
+    end
+
     def self.all(repo_path: Hiiro::REPO_PATH)
       git = Hiiro::Git.new(nil, repo_path)
       git.worktrees(repo_path: repo_path).filter_map do |wt|
@@ -1485,6 +1550,10 @@ class Hiiro
       !subtask?
     end
 
+    def absolute_tree?
+      tree_name.to_s.start_with?('/')
+    end
+
     def tree
       @tree ||= Environment.current&.find_tree(tree_name)
     end
@@ -1649,7 +1718,7 @@ class Hiiro
         t = tree
         all_tasks.find { |task|
           (s && task.session_name == s.name) ||
-            (t && task.tree_name == t.name)
+            (t && (task.tree_name == t.name || task.tree_name == t.path))
         }
       end
     end
@@ -1659,7 +1728,7 @@ class Hiiro
     end
 
     def tree
-      @tree ||= all_trees.find { |t| t.match?(path) }
+      @tree ||= all_trees.find { |t| t.match?(path) } || external_task_tree
     end
 
     def find_task(abbreviated)
@@ -1682,6 +1751,8 @@ class Hiiro
 
     def find_tree(abbreviated)
       return nil if abbreviated.nil?
+      return Tree.from_path(abbreviated) if abbreviated.to_s.start_with?('/') && Dir.exist?(abbreviated)
+
       tree_matcher.find(abbreviated).first&.item
     end
 
@@ -1694,5 +1765,10 @@ class Hiiro
       return nil if abbreviated.nil?
       app_matcher.find(abbreviated).first&.item
     end
+
+    def external_task_tree
+      task = all_tasks.find { |t| t.absolute_tree? && t.tree_name && (path == t.tree_name || path.start_with?(t.tree_name + '/')) }
+      Tree.from_path(task.tree_name) if task
+    end
   end
 end

data/lib/hiiro/tui.rb

@@ -0,0 +1,216 @@
+require 'io/console'
+
+class Hiiro
+  module Tui
+    module Terminal
+      def with_screen
+        input = $stdin
+        $stdout.write("\e[?1049h\e[?25l")
+        $stdout.flush
+
+        input.raw do
+          yield input
+        end
+      ensure
+        $stdout.write("\r\e[0m\e[?25h\e[?1049l")
+        $stdout.flush
+      end
+
+      def read_key(input)
+        char = input.getch
+        return :ctrl_c if char == "\u0003"
+        return :enter if char == "\r" || char == "\n"
+
+        if char == "\e"
+          first = read_escape_char(input)
+          return :escape if first.nil?
+          return :escape unless first == '['
+
+          case read_escape_char(input)
+          when 'A' then :up
+          when 'B' then :down
+          when 'C' then :right
+          when 'D' then :left
+          else :escape
+          end
+        else
+          char
+        end
+      end
+
+      def read_escape_char(input)
+        return nil unless IO.select([input], nil, nil, 0.02)
+
+        input.getch
+      end
+
+      def terminal_rows
+        env_dimension('LINES') || IO.console.winsize[0]
+      rescue StandardError
+        24
+      end
+
+      def terminal_cols
+        env_dimension('COLUMNS') || IO.console.winsize[1]
+      rescue StandardError
+        80
+      end
+
+      def terminal_line(text, cols)
+        truncate(text, cols) + "\e[K"
+      end
+
+      def center_text(text, cols)
+        truncated = truncate(text, cols)
+        return truncated if truncated.length >= cols
+
+        left_padding = [(cols - truncated.length) / 2, 0].max
+        (' ' * left_padding) + truncated
+      end
+
+      def truncate(text, cols)
+        return text if text.length <= cols
+        return text[0, cols] if cols <= 1
+
+        text[0, cols - 1] + '…'
+      end
+
+      def visible_text(text, cols, offset = 0)
+        return truncate(text, cols) if offset <= 0
+
+        clipped = text[offset..] || ''
+        return truncate(clipped, cols) if cols <= 1
+
+        truncate("«#{clipped}", cols)
+      end
+
+      def env_dimension(name)
+        value = ENV[name].to_i
+        return nil unless value.positive?
+
+        value
+      end
+    end
+
+    class ListScreen
+      include Terminal
+
+      attr_reader :items, :cursor, :top, :horizontal_offset
+
+      def initialize(items:, empty_message: 'No items.')
+        @items = items
+        @empty_message = empty_message
+        @cursor = 0
+        @top = 0
+        @horizontal_offset = 0
+      end
+
+      def run
+        if items.empty?
+          puts @empty_message
+          return false
+        end
+
+        with_screen do |input|
+          loop do
+            render
+
+            result = handle_key(read_key(input))
+            return result unless result == :continue
+          end
+        end
+      end
+
+      def handle_key(key)
+        case key
+        when :up, 'k'
+          move(-1)
+        when :down, 'j'
+          move(1)
+        when :left, 'h'
+          scroll_horizontal(-4)
+        when :right, 'l'
+          scroll_horizontal(4)
+        when 'q', :escape, :ctrl_c
+          return false
+        end
+
+        :continue
+      end
+
+      def render
+        rows = terminal_rows
+        cols = terminal_cols
+        line_cols = [cols - 1, 1].max
+        headers = header_lines
+        visible_rows = [rows - headers.length - footer_height, 1].max
+        visible = items[@top, visible_rows] || []
+        @horizontal_offset = [horizontal_offset, max_horizontal_offset(line_cols, visible)].min
+
+        lines = headers.map { |line| terminal_line(line, line_cols) }
+        visible.each_with_index do |item, idx|
+          lines << format_row(item, @top + idx == cursor, line_cols)
+        end
+
+        (visible_rows - visible.length).times { lines << terminal_line('', line_cols) }
+        footer_lines.each { |line| lines << terminal_line(line, line_cols) }
+
+        $stdout.write("\e[H\e[2J")
+        $stdout.write(lines.join("\r\n"))
+        $stdout.write("\r")
+        $stdout.flush
+      end
+
+      def header_lines
+        []
+      end
+
+      def footer_lines
+        ["Showing #{@top + 1}-#{@top + visible_items.length} of #{items.length}"]
+      end
+
+      def footer_height
+        1
+      end
+
+      def format_row(item, current, line_cols)
+        prefix = current ? '> ' : '  '
+        style = current ? "\e[7m" : "\e[0m"
+        text = (prefix + visible_text(item.to_s, [line_cols - prefix.length, 1].max, horizontal_offset)).ljust(line_cols)
+
+        "#{style}#{text}\e[0m\e[K"
+      end
+
+      def move(delta)
+        @cursor = [[cursor + delta, 0].max, items.length - 1].min
+        visible_rows = body_rows_budget
+        @top = cursor if cursor < top
+        @top = cursor - visible_rows + 1 if cursor >= top + visible_rows
+        @horizontal_offset = [horizontal_offset, max_horizontal_offset].min
+      end
+
+      def scroll_horizontal(delta)
+        @horizontal_offset = [[horizontal_offset + delta, 0].max, max_horizontal_offset].min
+      end
+
+      def visible_items
+        items[top, body_rows_budget] || []
+      end
+
+      def body_rows_budget
+        [terminal_rows - header_lines.length - footer_height, 1].max
+      end
+
+      def max_horizontal_offset(line_cols = nil, visible = nil)
+        line_cols ||= [terminal_cols - 1, 1].max
+        visible ||= visible_items
+        return 0 if visible.empty?
+
+        longest_visible_item = visible.map { |item| item.to_s.length }.max || 0
+        min_visible_chars = [5, line_cols].min
+
+        [longest_visible_item - min_visible_chars, 0].max
+      end
+    end
+  end
+end

data/lib/hiiro/version.rb

@@ -1,3 +1,3 @@
 class Hiiro
-  VERSION = "0.1.352"
+  VERSION = "0.1.354"
 end

data/lib/hiiro.rb

@@ -47,6 +47,7 @@ require_relative "hiiro/pane_home"
 require_relative "hiiro/pin_record"
 require_relative "hiiro/reminder"
 require_relative 'hiiro/registry'
+require_relative 'hiiro/tui'
 
 class String
   def underscore(camel_cased_word=self)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: hiiro
 version: !ruby/object:Gem::Version
-  version: 0.1.352
+  version: 0.1.354
 platform: ruby
 authors:
 - Joshua Toyota
@@ -377,6 +377,7 @@ files:
 - lib/hiiro/tmux/window.rb
 - lib/hiiro/tmux/windows.rb
 - lib/hiiro/todo.rb
+- lib/hiiro/tui.rb
 - lib/hiiro/version.rb
 - notes
 - obsidian_slides.md