hiiro 0.1.390 → 0.1.392

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e9c16c581ea6c758abd518a2f706d980cd7e7d4f2c0efad6fb8f99de4ba8fcdb
-  data.tar.gz: 85fbe331a3e3ddf3fd36adfb3864d5f4d131a17714be759a65eaf79940f423ce
+  metadata.gz: ad2d60d5740dd8e55e05cb747b2bd6b5e29a04e0afea78044d27b8bd07d89d4b
+  data.tar.gz: edbb5719e7e2e7fca15751c62140f1c1ef8eb25f62d52a8d3e4d9369e86d400c
 SHA512:
-  metadata.gz: ab5e23b6ebe2c5e0fbfb17000ce471c965efc3988777e346d15bbaeb54d1bc3ca1479f0ed21c98a52a0f959d1066f6c0c936a665e71ba29d3132c6f64c70062d
-  data.tar.gz: eb6a4353ae61c553c5f1cf524e18548161ff201a465cdf682ea04e897028b6b7df56ce356fd57259ddc7fd3951370b8ad65691453bbf6995c25a68869af2159b
+  metadata.gz: 3b77ec5fd8c0035039f265df261e982d7e02d730292fdf91196322cce5dba1ce66683e058cbd5816c02d1dc9f5cb1392e32ff8a4638f3766413b8ed28f57db75
+  data.tar.gz: 1dfc40943e3a3dcd494eae3f0f9ca642b4cbf926db55a5a64ff256003a1fc7b2bb556677c47cdb1b0a2058b8fab42c836424e6b363cf586cae76e6b8190805f5

data/AGENTS.md

@@ -24,6 +24,18 @@ Tests are organized under `test/`:
 
 The `Hiiro::TestHarness` class (in `test/test_helper.rb`) enables testing bin files by capturing the block passed to `Hiiro.run` and evaluating it in a test context with stubbed `system` calls.
 
+
+## Making Changes
+
+Hiiro is extensible, and when working on a bin or subcommand, there could be
+multiple variations of a bun and which one the user assumes is latest might not
+be accurate.  The common places for these bins are:
+
+- ~/bin/
+- ~/proj/phome/bin/
+- ~/proj/hiiro/bin/
+- any version of the gem installed via rbenv
+
 ## Architecture
 
 ### Core Components (bin/h)
@@ -239,6 +251,59 @@ end
 - `h db migrate` — re-run YAML import (if not yet migrated)
 - `h db restore` — restore YAML files from SQLite data
 
+### Hiiro::Table / Hiiro::TableScope / Hiiro::TableActions (lib/hiiro/table*.rb)
+
+A **table** is one named key/value list, stored as `registry.resource_type`; an **entry** is one `RegistryEntry` row. `RegistryEntry` has a nullable `task_id` and `tags` / `tag(*names)` / `untag(*names)` through `Hiiro::Tag` (taggable_type `RegistryEntry`).
+
+```ruby
+Hiiro::Table.all                       # every table, sorted by name
+t = Hiiro::Table.named('link')         # exists? is false until a row is added
+t.add('gh', value: 'https://github.com', short: 'g', desc: '', meta: {}, task_id: nil)
+t.entries(scope: Hiiro::TableScope.global)   # rows ordered by name; count(scope:) ; find(ref)
+t.rename('links')                      # moves every row; raises Hiiro::Error if the target exists
+
+scope = Hiiro::TableScope.current      # task scope when CurrentTask resolves one, else global
+scope.task? / scope.global? / scope.label   # "task(@NAME)" | "global"
+scope.toggle                           # task -> global keeps the task; global -> task re-uses or resolves it
+scope.apply(dataset)                   # the only place that knows task scope means where(task_id:)
+
+acts = Hiiro::TableActions.load        # ~/.config/hiiro/tables.yml: { 'link' => { 'c' => 'cd {value}' } }
+acts.for(entry)                        # DEFAULTS (o open, y pbcopy) merged with the table's letters
+acts.command('o', entry)               # {value} {name} {table} shell-escaped; nil when no action
+acts.run('o', entry)                   # system('/bin/sh', '-c', cmd); returns cmd
+```
+
+`bin/h-table` is the TUI (`Hiiro::TableScreen` in lib/hiiro/table_screen.rb: `TableScreen.new(scope:, table:, actions:)`, `reload!`, `marked`) and the scriptable CLI (`tables`, `ls`, `add`, `rm`, `mv`, `set`, `get`, `tag`, `untag`) over these tables; `h registry` is the same rows. See `docs/h-table.md`.
+
+`t ui` is the second screen on the toolkit: `Hiiro::TaskScreen` (lib/hiiro/task_screen.rb, `TaskScreen.new(scope: :global, current:, show_closed: false, ops:)`, `reload!`, `expanded`) is a tree of task/subtask/todo nodes; edits go through `TaskRecord#set_next!` / `#set_waiting!` / `#set_status!`, `TodoItem#update_status`, and `TaskScreen::Ops` (create, save_current, open_workspace over `TaskCli::Commands`, stdout captured). See `docs/t.md`.
+
+`h project ui` is the third screen on the toolkit: `Hiiro::ProjectCatalog.load(roots:, aliases:)` (lib/hiiro/project_catalog.rb; `default_roots` is `~/proj` and `WORK_DIR`, `rows` / `repos` / `reload` / `repo_for(row)`; a `Row` is `{ name, path, kind: :tree | :dir | :alias, repo, branch, head }`, `key` is the path, `main?` is the repo's first worktree) lists one row per git worktree under the roots plus plain dirs and `project` aliases, grouping a repo's worktrees by `Git::Worktrees.fetch` so an extra tree reads `repo ▸ tree`. `Hiiro::ProjectScreen.new(catalog:, scope:, current:, facts:, opener:, fetcher:)` (lib/hiiro/project_screen.rb, `reload!`, `rebuild!`) draws it; `Facts` caches `status[tree_path]` / `branches[repo_path]` / `prs[repo_path]` fetched on `s` / `b` / `p` through `Fetcher` (git and `gh pr list`), `Opener#open(row)` runs `tuios new-window` under `TUIOS_ENV=1` (`command(row)` is the argv) and `Herdr.open_workspace` otherwise, and `a` / `d` add and remove worktrees through git. See `docs/h-project.md`.
+
+### Hiiro::Tui (lib/hiiro/tui.rb)
+
+Screen toolkit for in-process TUIs. One engine for every hiiro TUI; do not add curses or shell out to a fuzzy finder for a screen (see `docs/plans/hiiro-tui.md`).
+
+```ruby
+class MyScreen < Hiiro::Tui::Screen
+  key 'o', :open_item                 # key map is a table; subclasses add or override bindings
+  def header_lines = ["title  #{state.query}"]
+  def detail_lines(item) = ["name  #{item.name}"]   # nil (default) means no detail pane
+  def pick_candidates = %w[link sound]              # '@' opens a prefix-filtered picker in the status line
+  def picked(candidate) = (self.message = candidate)
+  def open_item = (self.message = "open #{current_item}")
+  def unhandled_key(key) = nil                       # list-mode keys the key map does not bind
+  def ask = prompt('name', default: 'x') { |text| prompt('value') { |v| save(text, v) } }
+end
+MyScreen.new(items: rows).run        # j/k/h/l move, '/' searches, '@' picks, q/Esc/Ctrl-C quit
+```
+
+- `state` is one `Tui::State` (`mode` :list|:search|:pick|:prompt, `cursor`, `top`, `horizontal_offset`, `query`, `pick_query`, `message`, `prompt_label`, `prompt_text`). Read it; never keep a parallel boolean.
+- `prompt(label, default: '') { |text| ... }` reads one line in the status line (`label: text_`). Enter leaves the mode and calls the block, Esc leaves without calling it, Ctrl-C quits. The block runs after the prompt closes, so it may call `prompt` again to chain questions.
+- `unhandled_key(key)` is called from list mode for any key the key map does not bind (default no-op); `TableScreen` uses it for per-table action letters.
+- `frame(rows:, cols:)` returns plain strings with no ANSI, one per row, which is what tests assert against literally. `render` adds the highlight.
+- `Tui::Pane.new(width:, height:).lines(texts)` pads and truncates to an exact rectangle.
+- `ListScreen` is `Screen` without a detail pane and keeps the `Showing a-b of n` footer.
+
 ### Hiiro::Fuzzyfind (lib/hiiro/fuzzyfind.rb)
 
 Integration with `sk` (skim) or `fzf` fuzzy finders:
@@ -371,9 +436,9 @@ loc.target                                    # pane_id || tab_id || workspace_i
 loc.to_meta                                   # inverse of from_meta (queue/service metadata)
 ```
 
-### Hiiro::Link / Hiiro::URLTemplate (lib/hiiro/link.rb)
+### Hiiro::URLTemplate (lib/hiiro/link.rb)
 
-`bin/h-link` uses `Hiiro::Link` directly (its inline `LinkManager::Link` copy is gone). `Link.from_hash(yaml_row)` builds an unsaved instance; `to_h` / `to_yaml` give the links.yml shape.
+Saved links are the `link` registry table (url → value, shorthand → short_name, description, created_at for the numbered order); `bin/h-link` reads and writes them through `Hiiro::Table.named('link')` and wraps each `RegistryEntry` in its own `LinkPresenter`. `h link path` prints the database path. `DB.import_tables!` imported the legacy `links` table (kept for the installed gem) and `links.yml` (renamed `.bak`) once; `Hiiro::DB.link_name(url, shorthand, description)` picks the entry name.
 
 ```ruby
 t = Hiiro::URLTemplate.new('https://x/{org}/{repo}', values: { 'org' => 'a b' })
@@ -660,16 +725,17 @@ ALWAYS update `README.md` and any files in `docs/` or other markdown files that
 
 All config lives in `~/.config/hiiro/`:
 - `plugins/` - Auto-loaded plugin files
-- `pins/` - Per-command YAML key-value storage
+- `pins/` - Legacy per-command pin files. Pins now live in registry tables named after the command (e.g. table `t`, entry `current_task`); `pins/*` files and `sounds.yml` are imported once into tables `<name>` and `sound` by `Hiiro::DB.import_tables!` and renamed `.bak`
 - `tasks/` - Task metadata for worktree management
 - `queue/` - Prompt queue (wip, pending, running, done, failed)
 - `services/` - Service runtime state
 - `jumplist/` - Per-client tmux navigation history
 - `env_templates/` - Base .env template files for services
-- `projects.yml` - Project directory aliases
+- `projects.yml` - Legacy project aliases; imported once into registry table `project` and renamed `.bak`. Aliases now live in that table; `h project edit` edits it through a YAML buffer
 - `apps.yml` - App directory mappings for task plugin
 - `services.yml` - Service and service group definitions
 - `tools.yml` - Runner tool definitions
+- `tables.yml` - Per-table action letters for `h table`
 - `app_files.yml` - Per-app tracked file lists
 
 

data/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## [0.1.392] - 2026-10-12
+
+### Changed
+- `add_cmd` accepts `opts`, `flags`, and `mopts` arrays for value options, boolean flags, and repeated value options. Existing definitions are reused, and new short names use the first available alphanumeric character in the full name.
+- Automatic command definitions are registered for reuse by later commands. Existing boolean callers now use `flags`.
+
 ## [0.1.390] - 2026-10-07
 
 ### Added
@@ -18,6 +24,9 @@
 
 ## Unreleased
 
+### Fixed
+- Fix `PsProcess::Snapshot.capture` constant lookup, which raised `NameError` in `h ps byport`, `h ps indir`, and parent/child process lookups.
+
 ### Added
 - `h herdr` and `hh` pane controls for Vim-style focus, two-pane reflow, resize, swap, and zoom
 - `prefix+shift+h/j/k/l` reflows a two-pane tab toward an edge; `prefix+alt+h/j/k/l` resizes the current pane

data/README.md

@@ -59,6 +59,13 @@ h ping
 # => pong
 ```
 
+### Find processes by port
+
+`h ps byport 4399` prints each matching process PID and working directory,
+separated by a tab. Pass multiple ports with `h ps byport 4399 3000`.
+If no processes match, it prints `No processes found on port(s): 4399`.
+This command requires `ps` and `lsof`.
+
 ### Save clipboard content
 
 `h save` saves whatever is on the macOS clipboard to `~/saved/` and prints the
@@ -196,7 +203,7 @@ See the [task command reference](docs/t.md) for all commands and the [workflow i
 | `h edit` | Open the h script in your editor |
 | `h alert` | macOS desktop notifications via terminal-notifier |
 | `h herdr` | Herdr task popups plus Vim-style pane focus, movement, resize, swap, and zoom controls (`h herdr install`) |
-| `h task` | Same program as `t`: task records, todos, worktrees (`t NAME tree new`), and Herdr workspaces |
+| `h task` | Same program as `t`: task records, todos, worktrees (`t NAME tree new`), and Herdr workspaces; `t ui` is a tree TUI over tasks, subtasks, and todos |
 
 ### External Subcommands
 
@@ -215,13 +222,15 @@ See the [task command reference](docs/t.md) for all commands and the [workflow i
 | `h pane` | Herdr pane management |
 | `h plugin` | Manage hiiro plugins (list, edit, search) |
 | `h pr` | GitHub PR management via gh CLI |
-| `h project` | Project navigation with Herdr workspace management |
+| [`h project`](docs/h-project.md) | Project navigation with Herdr workspace management; `h project ui` is the projects screen over every worktree, directory, and alias |
 | `h queue` | Claude prompt queue with Herdr-based task execution |
+| `h registry` | Named resources by type with short aliases; the same rows as `h table` |
 | `h service` | Manage background dev services with env variations and groups |
 | `h file` | Track and open frequently-used files per app |
 | `h run` | Run dev tools (lint/test/format) against changed files |
 | `h session` | Compatibility commands for Herdr workspaces |
 | `h sha` | Extract short SHA from git log |
+| [`h table`](docs/h-table.md) | TUI and scriptable CLI over registry tables (links, sounds, pins, ...) with task scope, tags, and per-table actions |
 | `h todo` | Todo list management with tags and task association |
 | `h window` | Compatibility commands for Herdr tabs |
 | `h wtree` | Git worktree management |
@@ -339,15 +348,18 @@ 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.
+Use `add_cmd` to expose a command's options in help. Choose a declaration bucket
+for each undeclared name:
+
+- `opts:` creates a string-valued option with a default of `nil`.
+- `flags:` creates a boolean flag with a default of `false`. Flags do not consume the next positional argument.
+- `mopts:` creates a repeatable string-valued option with a default of `[]`.
 
 ```ruby
 Hiiro.run do
   add_option :task, short: :t, desc: 'Task name'
 
-  add_cmd :test, opts: %i[a b c d task] do
+  add_cmd :test, opts: %i[task], flags: %i[a b c d], mopts: %i[tag] do
     puts 'a was set' if opts.a
     puts opts.task if opts.task
     puts opts.args
@@ -355,15 +367,20 @@ Hiiro.run do
 end
 ```
 
-Here, `test -a payload -t investigation` sets `opts.a` to `true`, leaves
-`payload` in `opts.args`, and sets `opts.task` to `investigation`.
+Here, `test -a payload -t investigation --tag ruby --tag cli` sets `opts.a`
+to `true`, leaves `payload` in `opts.args`, sets `opts.task` to
+`investigation`, and sets `opts.tag` to `['ruby', 'cli']`.
 `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.
+Names accept strings or symbols and are deduplicated across the buckets.
+Existing definitions keep their type, default, short alias, and description,
+regardless of the bucket used to select them. New definitions are
+registered on the parent option set so later commands reuse them.
+
+Automatic short aliases use the first unused alphanumeric character in the full
+name, scanning left to right. All existing short aliases and `-h` are reserved;
+aliases are never reassigned. A name with no available character has only its long form.
 
 For a command that delegates to `run_child`, use `add_cmd(..., passthrough: true)`.
 It forwards control without parsing the parent's arguments or intercepting the
@@ -433,12 +450,13 @@ All configuration lives in `~/.config/hiiro/`:
 ```
 ~/.config/hiiro/
   plugins/        # Plugin files (auto-loaded)
-  pins/           # Pin storage (per command)
+  pins/           # Legacy pin files; imported once into registry tables named after the command (h-sha -> sha), then renamed .bak
+  sounds.yml      # Legacy; imported once into registry table sound, then renamed .bak
   services/       # Service runtime state
   bg-history.txt  # Background command history
   env_templates/  # Base .env templates for services
   tasks/          # Task metadata
-  projects.yml    # Project aliases
+  projects.yml    # Legacy; imported once into registry table project, then renamed .bak (edit aliases with h project edit)
   apps.yml        # App directory mappings
   services.yml    # Service and service group definitions
   tools.yml       # Runner tool definitions

data/bin/h-alias

@@ -5,7 +5,7 @@ require 'hiiro'
 Hiiro.run do
   add_flag :global, short: :g, desc: 'Create a global zsh alias'
 
-  add_cmd :add, args: ['NAME', 'COMMAND...'], opts: [:global] do
+  add_cmd :add, args: ['NAME', 'COMMAND...'], flags: [:global] do
     abort 'Usage: h alias add [--global|-g] NAME COMMAND...' unless opts.args.length >= 2
     name, *command_args = opts.args
     abort 'Invalid alias name' unless /\A[A-Za-z0-9_.][A-Za-z0-9_.-]*\z/.match?(name)

data/bin/h-date

@@ -8,13 +8,13 @@ Hiiro.run(*ARGV) do
   add_flag(:utc, short: :u, desc: 'Output in UTC')
 
   # h date to_unix [date-string]  -> unix seconds (or ms with --ms)
-  add_cmd(:to_unix, :unix, :ts, opts: %i[ms]) do
+  add_cmd(:to_unix, :unix, :ts, flags: %i[ms]) do
     t = Hiiro::TimeInput.parse(@opts.args.join(' '))
     puts @opts.ms ? t.unix_milliseconds : t.unix_seconds
   end
 
   # h date from_unix <timestamp>  -> human date (auto-detects ms by digit count)
-  add_cmd(:from_unix, :parse, opts: %i[ms utc]) do
+  add_cmd(:from_unix, :parse, flags: %i[ms utc]) do
     raw = @opts.args.first or abort 'usage: h date from_unix <timestamp> [--ms] [--utc]'
     t = Hiiro::TimeInput.parse(raw, ms: @opts.ms ? true : nil)
     t = t.utc if @opts.utc
@@ -22,7 +22,7 @@ Hiiro.run(*ARGV) do
   end
 
   # h date fmt Y-m-d H:M:S  -> strftime with % auto-inserted before each char
-  add_cmd(:fmt, :format, :strftime, opts: %i[utc]) do
+  add_cmd(:fmt, :format, :strftime, flags: %i[utc]) do
     fmt = @opts.args.join(' ')
     abort 'usage: h date fmt <strftime-chars-without-percent>' if fmt.empty?
     with_percent = fmt.gsub(/[A-Za-z%]/) { |c| c == '%' ? '%%' : "%#{c}" }
@@ -30,20 +30,20 @@ Hiiro.run(*ARGV) do
     puts t.strftime(with_percent)
   end
 
-  add_cmd(:now, opts: %i[utc]) do
+  add_cmd(:now, flags: %i[utc]) do
     t = @opts.utc ? Time.now.utc : Time.now
     puts t.iso8601
   end
 
   # h date dur <seconds>  -> 1d23h12m10s  (--ms to interpret input as milliseconds)
-  add_cmd(:dur, :duration, :human, opts: %i[ms]) do
+  add_cmd(:dur, :duration, :human, flags: %i[ms]) do
     raw = @opts.args.first or abort 'usage: h date dur <seconds> [--ms]'
     n = Rational(raw.to_s)
     puts (@opts.ms ? Hiiro::Duration.milliseconds(n) : Hiiro::Duration.seconds(n)).compact
   end
 
   # h date diff <a> <b>  -> how far apart two dates are (dates or unix timestamps)
-  add_cmd(:diff, opts: %i[ms]) do
+  add_cmd(:diff, flags: %i[ms]) do
     a, b = @opts.args
     abort 'usage: h date diff <date-a> <date-b>  (each: date string or unix timestamp)' unless a && b
     ta = Hiiro::TimeInput.parse(a, ms: @opts.ms ? true : nil)

data/bin/h-db

@@ -188,7 +188,6 @@ Hiiro.run(*ARGV) do
       apps:        %w[name],
       projects:    %w[name],
       assignments: %w[worktree],
-      pins:        %w[command key],
       pane_homes:  %w[name],
       check_runs:  %w[pr_number name],
       reminders:   %w[text],

data/bin/h-git

@@ -215,7 +215,7 @@ Hiiro.run(*ARGV, plugins: [Pins]) do
     end
   end
 
-  add_cmd(:commit, opts: %i[dry_run yes model]) do
+  add_cmd(:commit, opts: %i[model], flags: %i[dry_run yes]) do
     unless system('git', 'rev-parse', '--is-inside-work-tree', out: File::NULL, err: File::NULL)
       puts 'Not inside a git work tree.'
       next false