hiiro 0.1.385 → 0.1.387.pre.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1877449a8336392c36f54f38f1ea86792b736f6d8af25bea8bb98f1f62081328
-  data.tar.gz: 495465e2395a43cc24464922aa60e24283e97bf715f7492f7be182e8936629c6
+  metadata.gz: acd7043754dc01539f98a7f622e8201bf06799e41f540f3901eedca29ad28235
+  data.tar.gz: 7f37ee293a6e11a7ef5f8f85682891e9e4773d91fbd79a2f6e561a1e6ec8764b
 SHA512:
-  metadata.gz: 0d1c6e96f27300ab32b675f10b2d00c207792a0534859bbbfaa02f72d855b3af33572422842474cdfddf3a18cd5146eb93060349b03671232b4b4485c262079d
-  data.tar.gz: 0db00cb34ddc01b743a1a3f039e80308619134ce722e9f316cc483f36c1db1579d749218be66ab30e31b664996f6eeb9e89a6ffacff6c1763ce8d47dc8193e7e
+  metadata.gz: 5b2177c62610d52720d1672ad276c79e8b928aa021daf9e813c41752c1c6b22b83564a6893736e0cd3369e03270cddf18b361135841b8ec94fd31fcf8a0a7f43
+  data.tar.gz: b250d4434fd950326aff95fd35b52a2c8cba8024ea89ebbee2525b28d816615fea788136f83798170e7a2ac1d5f3080ccbf440158ca3b803ff3b646dd166178b

data/AGENTS.md

@@ -187,6 +187,8 @@ Hiiro::Matcher.by_prefix(items, "pre", key: :name)
 Hiiro::Matcher.by_substring(items, "abc", key: :name)
 ```
 
+`Result` and `PathResult` share their cardinality/resolution answers through `Hiiro::Matcher::ResultQueries` (`count`, `one?`, `ambiguous?`, `match?`, `exact_match`, `exact?`, `match`, `resolved`, `first`); both expose the original query as `query`.
+
 Note: `Hiiro::PrefixMatcher` is aliased to `Hiiro::Matcher` for backward compatibility.
 
 ### Hiiro::Git (lib/hiiro/git.rb)
@@ -198,7 +200,8 @@ git = hiiro.git
 git.root                          # Repository root path
 git.branch                        # Current branch name
 git.branches                      # List all branches
-git.worktrees                     # List all worktrees
+git.worktrees                     # List all worktrees (Git::Worktree: path, head, branch, bare?, detached?, name, to_line)
+Hiiro::Git::Worktrees.fetch       # Porcelain-backed collection; bins should use this instead of splitting `git worktree list`
 git.add_worktree(path, branch:)   # Create worktree
 git.move_worktree(from, to)       # Rename worktree
 git.current_pr                    # Get current PR info
@@ -281,6 +284,130 @@ Or via `h db q`:
 h db q "SELECT bin_name, argv_json, invoked_at FROM invocations ORDER BY invoked_at DESC LIMIT 10"
 ```
 
+### Hiiro::InputFile / Hiiro::EditedDocument (lib/hiiro/input_file.rb)
+
+Tempfile + editor lifecycle for YAML/markdown input. After `edit`, the result is retained as an `EditedDocument`:
+
+```ruby
+input = yaml_input_file(content: yaml, prefix: 'todo-edit-')   # or InputFile.yaml_file(hiiro:, ...) / .md_file
+doc   = input.edit.document        # EditedDocument: original, result (alias contents), parsed (alias data), error
+doc.changed? / doc.empty? / doc.valid?
+input.parsed_file                  # still available; nil on YAML parse error
+input.cleanup                      # unlink the tempfile when done
+```
+
+Use this instead of a hand-rolled Tempfile/system/YAML.load/unlink cycle (TodoManager#edit_items now does).
+
+### Hiiro::CheckSummary / Hiiro::CheckContext (lib/hiiro/check_summary.rb)
+
+One interpretation of a PR's `statusCheckRollup`, shared by `Git::Pr`, `PinnedPr`, `PinnedPRManager` display, `CheckRun` persistence, and `h pr status`:
+
+```ruby
+s = Hiiro::CheckSummary.from_rollup(rollup, truncated: false)   # nil when rollup nil/empty
+s = pr.check_summary                                             # from stored counts (+ raw contexts when present)
+s.total / s.success / s.pending / s.failed / s.frozen / s.complete?
+s.red? / s.green? / s.pending?        # the -r / -g / -p filter predicates (pr.red? etc. delegate here)
+s.any_pending? / s.only_frozen?       # display distinctions
+s.counts_by_outcome                   # { 'SUCCESS' => 12, 'FAILURE' => 1 } (missing keys read 0)
+s.contexts.each { |c| c.kind (:check_run|:status_context) ; c.name ; c.url ; c.outcome ; c.raw }
+s.to_h                                # the stored { 'total','success','pending','failed','frozen'[,'truncated'] } hash
+```
+
+### Hiiro::PullRequestReference / Hiiro::RepositoryIdentity (lib/hiiro/pull_request_reference.rb)
+
+```ruby
+ref = Hiiro::PullRequestReference.parse(input)   # URL | '#123' | '123' | 123 → ref, else nil
+ref.number / ref.number_string / ref.repo        # repo: RepositoryIdentity or nil for a bare number
+ref.key            # [number, 'owner/name'] — the key PinnedPRManager batches by
+ref.repo_args      # ['-R', 'owner/name'] or []
+ref.matches?(pr)   # same number; same repo when both sides know it
+pr.reference       # Git::Pr / PinnedPr → reference
+Hiiro::PinnedPr.find_by_reference(ref)           # repo-qualified lookup; legacy rows without repo still match
+Hiiro::RepositoryIdentity.parse('owner/name' | github URL)  # .host .owner .name .path .url
+```
+
+### Hiiro::Git::BranchComparison (lib/hiiro/git/branch_comparison.rb)
+
+Two refs plus an explicit base policy. Used by `h branch diff/changed/ahead/behind/log/forkpoint/ancestor`:
+
+```ruby
+cmp = git.compare(source: 'HEAD', target: nil, base_policy: :local_main, fallback: 'HEAD~1')
+# base_policy :local_main → main, master ; :remote_first → origin/master, master, origin/main, main
+cmp.target / cmp.target_source (:explicit|:policy|:fallback|:none) / cmp.resolved?
+cmp.ahead / cmp.behind / cmp.ancestor? / cmp.merge_base / cmp.fork_point (--fork-point, then merge-base)
+cmp.two_dot_range / cmp.three_dot_range / cmp.fork_range / cmp.changed_paths(relative: true)
+```
+
+`Hiiro::Git` gained the underlying queries: `ref_exists?`, `rev_list_count`, `merge_base`, `ancestor?`, `changed_files`.
+
+### Hiiro::TaskLocation (lib/hiiro/task_location.rb)
+
+Where a task's directories are. `CurrentTask` and `TaskCli` delegate `code_directory`, `workspace_label`, `tree_path`, `start_directory`, and `app_directory` to it:
+
+```ruby
+loc = Hiiro::TaskLocation.for(task, override: opts[:directory], app: Hiiro::App.new(name:, path:))
+loc.home             # TaskRecord.home_for(task.name); never creates it
+loc.worktree_path    # task.tree, absolute or under WORK_DIR; nil without a tree
+loc.code_directory   # task.primary_directory || worktree_path
+loc.app_directory    # app.resolve(code_directory); nil unless both known
+loc.start_directory  # override || app_directory || code_directory || home
+loc.source           # :override | :app | :primary | :tree | :home  (callers run ensure_home only for :home)
+loc.workspace_label  # (task.session || task.name).tr('.', '_')
+Hiiro::TaskLocation.contains?(root, path)   # realpath containment
+```
+
+### Hiiro::Herdr::TabCreation / Hiiro::Herdr::Location (lib/hiiro/herdr.rb)
+
+`tab create` responses are read through one value instead of `result.dig('tab','tab_id')` at every call site:
+
+```ruby
+created = Hiiro::Herdr::TabCreation.create(client, name:, workspace:, start_directory:, command:, focus:)  # or herdr.create_tab(**req)
+created.tab_id / created.pane_id / created.tab / created.root_pane
+created.created?   # tab id present          created.complete?  # tab + root pane present
+created.errors     # [] | ['no tab'] | ['no root pane']
+created.location(workspace_id: ws.id)       # Herdr::Location
+loc = Hiiro::Herdr::Location.from_meta(meta)  # reads herdr_workspace / herdr_tab / herdr_pane
+loc.target                                    # pane_id || tab_id || workspace_id
+loc.to_meta                                   # inverse of from_meta (queue/service metadata)
+```
+
+### Hiiro::Link / 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.
+
+```ruby
+t = Hiiro::URLTemplate.new('https://x/{org}/{repo}', values: { 'org' => 'a b' })
+t.placeholders     # ['org', 'repo']     t.placeholders?   # true
+t.missing_values   # ['repo']            t.complete?       # false
+t.url              # 'https://x/a+b/{repo}'  (spaces → '+', nothing else is encoded)
+```
+
+### Hiiro::PsProcess::Snapshot / OpenFiles (lib/hiiro/ps_process.rb)
+
+```ruby
+snap = Hiiro::PsProcess::Snapshot.capture      # one `ps awwux`; .processes .captured_at
+snap.by_pid(pid) / snap.with_pids(set) / snap.matching(pattern) / snap.parent_of(pid) / snap.children_of(pid)
+of = Hiiro::PsProcess::OpenFiles.for_pid(pid)  # one lsof; also .for_port(port), .in_dir(path), for_pid(pid, network_only: true)
+of.pids / of.cwd / of.files / of.sockets / of.failed   # failed = lsof exited non-zero (not the same as empty)
+```
+
+`PsProcess.by_port`, `.in_dirs`, `#files`, `#ports`, `#dir`, `#parent`, `#children` keep their shapes and read through these.
+
+### Hiiro::Duration / Hiiro::TimeInput (lib/hiiro/duration.rb, lib/hiiro/time_input.rb)
+
+Value objects behind `h date`, `h time`, and `h remind` (formerly duplicated helpers in each bin):
+
+```ruby
+Hiiro::Duration.parse('15m')            # => Duration(900s); nil when not <digits><s|m|h|d|w>
+Hiiro::Duration.seconds(90_061).compact # => "1d1h1m1s"   (.clock => "25:01:01", .components => {days:,hours:,...})
+Hiiro::Duration.milliseconds(1500)      # Rational-precise seconds
+
+t = Hiiro::TimeInput.parse('1726000000123')   # digits → unix; ms auto-detected past 11 digits (or ms: true)
+t.unit / t.time / t.unix_seconds / t.unix_milliseconds / t.utc / t.iso8601(3)
+Hiiro::TimeInput.parse('now') ; Hiiro::TimeInput.parse('2026-09-22 10:00')   # 'now'/blank → now ; else Time.parse
+a.difference(b)                          # => Duration
+```
+
 ### Hiiro::Shell (lib/hiiro/shell.rb)
 
 Utility for piping content to external commands:
@@ -288,8 +415,16 @@ Utility for piping content to external commands:
 ```ruby
 Hiiro::Shell.pipe("content", "pbcopy")           # Pipe string to command
 Hiiro::Shell.pipe_lines(["a", "b"], "command")   # Join array with newlines and pipe
+result = Hiiro::Shell.run('cmd', 'arg', SOME_ENV: 'x')   # Result: stdout, stderr, status, success?, lines, plain_text
+result.spec      # Hiiro::CommandSpecification — argv, env (normalized to strings), cwd, preview, open3_args
+result.command   # spec.preview, e.g. "cmd arg"
+content = Hiiro::Shell.read_input(*args)          # files named in args ('-' = stdin), else piped stdin
 ```
 
+`read_input` keeps only args that are readable paths (regular files, `/dev/fd/N`, `<(cmd)`) or `-`, concatenates them, and falls back to stdin when none remain. A named file wins over piped stdin unless `-` places it. At a terminal with no input it aborts with `no input: pipe data in or pass a file`.
+
+`run`, `run_combined`, `run3`, `stream`, and `stream_combined` all build one `CommandSpecification` and attach it to the `Result`.
+
 ### Hiiro::Options (lib/hiiro/options.rb)
 
 Argument parsing with flag and option support:
@@ -304,6 +439,8 @@ opts.verbose   # true if --verbose or -v was passed
 opts.args      # Remaining non-option arguments
 ```
 
+The declared options live in a `Hiiro::OptionSet` (`options.option_set`), which both `Options` and the parsed `Args` use for `help_text`, `hint`, `definition_for('--out' | '-o' | :out)`, `defaults`, `subset(names)`, and `conflicts_for(name)` (mutual-exclusion star topology).
+
 ### Hiiro::Notification (lib/hiiro/notification.rb)
 
 macOS notification wrapper using terminal-notifier:
@@ -334,7 +471,9 @@ Subcommands (`h queue <subcmd>`):
 Config: `~/.config/hiiro/queue/{wip,pending,running,done,failed}/`
 
 Key internals:
-- `Queue::Prompt` - Parses frontmatter to resolve task/tree/session for working directory
+- `Queue::Entry` - `Entry.find(dirs, name)` / `Entry.in(dirs, status)`; answers `prompt_path`, `meta_path`, `launcher_path`, `body_path`, `companion_files`, `modified_at`, `meta`, `preview`, `prompt`, `execution`, `moved_to(status)`, `to_h` ({ name:, status: }). `Queue#entry_for(name, status)` builds one; `tasks_in`, `all_tasks`, `meta_for`, `task_preview`, `find_task` are thin wrappers over it.
+- `Queue::Execution` - snapshot of a running entry's `.meta`: `started_at`, `elapsed` (Duration), `elapsed_minutes`, `working_directory`, `location` (Herdr::Location), `attach_target`
+- `Queue::Prompt` - Parses frontmatter to resolve task/tree/session for working directory; retains `path`; `body` strips frontmatter; `Prompt.frontmatter_lines(task_info:, ignore:, hints:)` is the editor template shared by add/wip
 - Tasks launch in tmux windows within the task's session (from frontmatter) or default `hq` session
 - Launcher script runs `cat prompt | claude`, then moves files to done/failed based on exit code
 
@@ -386,6 +525,9 @@ my-stack:
 ```
 
 Key internals:
+- `Hiiro::ServiceDefinition` (lib/hiiro/service_definition.rb) - `sm.definition_for(name)`; answers `base_directory`, `host`, `port`, `url`, `init_commands`, `start_command`, `stop_command`, `cleanup_commands`, `environment_files`
+- `Hiiro::EnvironmentFile` - one env file of a service: `template_path`, `destination_path`, `variables` ({ VAR => { variation => value } }), `selected_variation(var, overrides)` (default `local`), `effective_values(overrides)`, `desired_content(existing_lines, overrides)`. `h service env` displays it and `prepare_env` writes it; both read the same object.
+- `Hiiro::ServiceGroup` - `sm.group_definition_for(name)` / `ServiceGroup.from_config(name, cfg)`; `service_names`, `overrides_for(service_name)`
 - `prepare_env(svc_name, variation_overrides:)` - Copies base_env template from `~/.config/hiiro/env_templates/` to `base_dir/env_file`, then injects variation values
 - `find_group(name)` / `start_group(name, ...)` - Detect and start service groups, applying per-member `use:` overrides
 - Default variation is `local` when not specified

data/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## [0.1.387.pre.1] - 2026-10-01
+
+### Added
+- `Hiiro::Extractor` value object for data extraction
+- Support for Integer return values as exit codes from subcommand handlers
+
 ## Unreleased
 
 ### Added

data/bin/h-branch

@@ -235,12 +235,8 @@ Hiiro.run(*ARGV) do
       selected, status = Open3.capture2('sk', '--no-sort', stdin_data: lines.keys.join("\n"))
       return nil unless status.success? && !selected.strip.empty?
       lines[selected.chomp]
-    elsif arg.to_s =~ %r{/pull/(\d+)}
-      num = $1
-      pinned.find { |pr| pr.number.to_s == num }
-    elsif arg.to_s =~ /^#?(\d+)$/
-      num = $1
-      pinned.find { |pr| pr.number.to_s == num }
+    elsif (ref = Hiiro::PullRequestReference.parse(arg))
+      pinned.find { |pr| ref.matches?(pr) }
     end
   }
 
@@ -857,105 +853,51 @@ Hiiro.run(*ARGV) do
   }
 
   add_subcmd(:diff) { |*diff_args|
-    case diff_args.length
-    when 0
-      base = %w[main master].find { |b| system("git rev-parse --verify #{b} >/dev/null 2>&1") } || 'HEAD~1'
-      range = "#{base}..HEAD"
-    when 1
-      range = "#{diff_args[0]}..HEAD"
-    else
-      from, to = diff_args[0..1]
-      range = "#{from}..#{to}"
-    end
-
-    system('git', 'log', '--oneline', '--decorate', range)
+    cmp = git.compare(source: diff_args[1] || 'HEAD', target: diff_args[0], base_policy: :local_main, fallback: 'HEAD~1')
+    system('git', 'log', '--oneline', '--decorate', cmp.two_dot_range)
   }
 
   add_subcmd(:changed) { |*changed_args|
     show_all = changed_args.delete('-a') || changed_args.delete('--all')
-    upstream = changed_args.first
+    cmp = git.compare(target: changed_args.first, base_policy: :remote_first)
 
-    upstream ||= %w[origin/master master origin/main main].find { |ref|
-      system("git rev-parse --verify #{ref} >/dev/null 2>&1")
-    }
-
-    unless upstream
+    unless cmp.resolved?
       puts "Cannot find master or origin/master"
       next
     end
 
-    forkpoint = `git merge-base --fork-point #{upstream} HEAD 2>/dev/null`.strip
-    if forkpoint.empty?
-      forkpoint = `git merge-base #{upstream} HEAD 2>/dev/null`.strip
-    end
-
-    if forkpoint.empty?
+    unless cmp.fork_point
       puts "Could not find fork point"
       next
     end
 
-    if show_all
-      system('git', 'diff', '--name-only', "#{forkpoint}...HEAD")
-    else
-      system('git', 'diff', '--name-only', '--relative', "#{forkpoint}...HEAD")
-    end
+    puts cmp.changed_paths(relative: !show_all)
   }
 
   add_subcmd(:ahead) { |*ahead_args|
-    case ahead_args.length
-    when 0
-      base = %w[main master].find { |b| system("git rev-parse --verify #{b} >/dev/null 2>&1") } || 'HEAD~1'
-      ahead_of = base
-      branch = 'HEAD'
-    when 1
-      ahead_of = ahead_args[0]
-      branch = 'HEAD'
-    else
-      ahead_of, branch = ahead_args[0..1]
-    end
-
-    count = `git rev-list --count #{ahead_of}..#{branch}`.strip.to_i
-    puts "#{branch} is #{count} commit(s) ahead of #{ahead_of}"
+    cmp = git.compare(source: ahead_args[1] || 'HEAD', target: ahead_args[0], base_policy: :local_main, fallback: 'HEAD~1')
+    puts "#{cmp.source} is #{cmp.ahead} commit(s) ahead of #{cmp.target}"
   }
 
   add_subcmd(:behind) { |*behind_args|
-    case behind_args.length
-    when 0
-      base = %w[main master].find { |b| system("git rev-parse --verify #{b} >/dev/null 2>&1") } || 'HEAD~1'
-      behind_of = base
-      branch = 'HEAD'
-    when 1
-      behind_of = behind_args[0]
-      branch = 'HEAD'
-    else
-      behind_of, branch = behind_args[0..1]
-    end
-
-    count = `git rev-list --count #{branch}..#{behind_of}`.strip.to_i
-    puts "#{branch} is #{count} commit(s) behind #{behind_of}"
+    cmp = git.compare(source: behind_args[1] || 'HEAD', target: behind_args[0], base_policy: :local_main, fallback: 'HEAD~1')
+    puts "#{cmp.source} is #{cmp.behind} commit(s) behind #{cmp.target}"
   }
 
   add_subcmd(:log) { |upstream = nil|
-    upstream ||= %w[origin/master master origin/main main].find { |ref|
-      system("git rev-parse --verify #{ref} >/dev/null 2>&1")
-    }
+    cmp = git.compare(target: upstream, base_policy: :remote_first)
 
-    unless upstream
+    unless cmp.resolved?
       puts "Cannot find master or origin/master"
       next
     end
 
-    forkpoint = `git merge-base --fork-point #{upstream} HEAD 2>/dev/null`.strip
-    if forkpoint.empty?
-      forkpoint = `git merge-base #{upstream} HEAD 2>/dev/null`.strip
-    end
-
-    if forkpoint.empty?
+    unless cmp.fork_point
       puts "Could not find fork point"
       next
     end
 
-    system('git', 'log', '--oneline', '--decorate', "#{forkpoint}..HEAD")
+    system('git', 'log', '--oneline', '--decorate', cmp.fork_range)
   }
 
   add_subcmd(:q, :query) { |*args|
@@ -1001,50 +943,32 @@ Hiiro.run(*ARGV) do
   }
 
   add_subcmd(:forkpoint) { |upstream = nil, branch = nil|
-    branch ||= 'HEAD'
-    upstream ||= %w[origin/master master origin/main main].find { |ref|
-      system("git rev-parse --verify #{ref} >/dev/null 2>&1")
-    }
+    cmp = git.compare(source: branch || 'HEAD', target: upstream, base_policy: :remote_first)
 
-    unless upstream
+    unless cmp.resolved?
       puts "Cannot find master or origin/master"
       next
     end
 
-    forkpoint = `git merge-base --fork-point #{upstream} #{branch} 2>/dev/null`.strip
-
-    if forkpoint.empty?
-      forkpoint = `git merge-base #{upstream} #{branch} 2>/dev/null`.strip
-    end
-
-    if forkpoint.empty?
-      puts "Could not find fork point between #{upstream} and #{branch}"
+    if cmp.fork_point
+      puts cmp.fork_point
     else
-      puts forkpoint
+      puts "Could not find fork point between #{cmp.target} and #{cmp.source}"
     end
   }
 
   add_subcmd(:ancestor) { |*ancestor_args|
-    case ancestor_args.length
-    when 0
-      base = %w[main master].find { |b| system("git rev-parse --verify #{b} >/dev/null 2>&1") }
-      unless base
-        puts "Cannot find main or master branch"
-        next
-      end
-      ancestor = base
-      descendant = 'HEAD'
-    when 1
-      ancestor = ancestor_args[0]
-      descendant = 'HEAD'
-    else
-      ancestor, descendant = ancestor_args[0..1]
+    cmp = git.compare(source: ancestor_args[1] || 'HEAD', target: ancestor_args[0], base_policy: :local_main)
+
+    unless cmp.resolved?
+      puts "Cannot find main or master branch"
+      next
     end
 
-    if system("git merge-base --is-ancestor #{ancestor} #{descendant}")
-      puts "Yes, #{ancestor} is an ancestor of #{descendant}"
+    if cmp.ancestor?
+      puts "Yes, #{cmp.target} is an ancestor of #{cmp.source}"
     else
-      puts "No, #{ancestor} is NOT an ancestor of #{descendant}"
+      puts "No, #{cmp.target} is NOT an ancestor of #{cmp.source}"
     end
   }
 end

data/bin/h-date

@@ -3,52 +3,20 @@
 require 'hiiro'
 require 'time'
 
-# Parse a timestamp string as unix seconds (10-digit) or milliseconds (13-digit)
-def parse_unix(str, ms: nil)
-  n = Rational(str.to_s)
-  ms = str.to_s.sub(/\..*/, '').length > 11 if ms.nil?
-  Time.at(ms ? n / 1000 : n)
-end
-
-def parse_date(str)
-  str.nil? || str.empty? || str == 'now' ? Time.now : Time.parse(str)
-end
-
-# Parse a value that is either a unix timestamp (digits) or a date string.
-def parse_date_or_unix(str, ms: false)
-  str.to_s =~ /^-?\d+(\.\d+)?$/ ? parse_unix(str, ms: ms ? true : nil) : parse_date(str)
-end
-
-# Format a number of seconds as a compact human duration: 1d23h12m10s
-def human_duration(total_secs)
-  total = total_secs.to_f
-  sign = total.negative? ? '-' : ''
-  total = total.abs.round
-  days, rem     = total.divmod(86_400)
-  hours, rem    = rem.divmod(3_600)
-  minutes, secs = rem.divmod(60)
-  parts = []
-  parts << "#{days}d"    if days > 0
-  parts << "#{hours}h"   if hours > 0
-  parts << "#{minutes}m" if minutes > 0
-  parts << "#{secs}s"    if secs > 0
-  sign + (parts.empty? ? '0s' : parts.join)
-end
-
 Hiiro.run(*ARGV) do
   add_flag(:ms, short: :m, desc: 'Use milliseconds instead of seconds')
   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
-    t = parse_date(@opts.args.join(' '))
-    puts @opts.ms ? (t.to_f * 1000).round : t.to_i
+    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
     raw = @opts.args.first or abort 'usage: h date from_unix <timestamp> [--ms] [--utc]'
-    t = parse_unix(raw, ms: @opts.ms ? true : nil)
+    t = Hiiro::TimeInput.parse(raw, ms: @opts.ms ? true : nil)
     t = t.utc if @opts.utc
     puts t.iso8601(3)
   end
@@ -71,15 +39,15 @@ Hiiro.run(*ARGV) do
   add_cmd(:dur, :duration, :human, opts: %i[ms]) do
     raw = @opts.args.first or abort 'usage: h date dur <seconds> [--ms]'
     n = Rational(raw.to_s)
-    puts human_duration(@opts.ms ? n / 1000 : n)
+    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
     a, b = @opts.args
     abort 'usage: h date diff <date-a> <date-b>  (each: date string or unix timestamp)' unless a && b
-    ta = parse_date_or_unix(a, ms: @opts.ms)
-    tb = parse_date_or_unix(b, ms: @opts.ms)
-    puts human_duration(tb - ta)
+    ta = Hiiro::TimeInput.parse(a, ms: @opts.ms ? true : nil)
+    tb = Hiiro::TimeInput.parse(b, ms: @opts.ms ? true : nil)
+    puts ta.difference(tb).compact
   end
 end

data/bin/h-docs

@@ -8,6 +8,8 @@ require 'uri'
 SERVER = ENV.fetch('HDOCS_SERVER', 'http://127.0.0.1:4387').sub(%r{/$}, '')
 DOCS_DIR = File.join(Dir.home, 'claude', 'docs')
 PROJECT_ROOT = ENV.fetch('PORTFOLIO_HOME', File.join(Dir.home, 'proj', 'portfolio'))
+DESKTOP_DIR = File.join(PROJECT_ROOT, 'apps/desktop')
+APP_PATH = File.join(DESKTOP_DIR, 'bin/desktop.app')
 SERVICE_LABEL = "com.#{ENV.fetch('USER')}.portfolio"
 SERVICE_DOMAIN = "gui/#{Process.uid}"
 SERVICE_TARGET = "#{SERVICE_DOMAIN}/#{SERVICE_LABEL}"
@@ -45,6 +47,10 @@ class PortfolioApi
     get('/health')
   end
 
+  def ports
+    get('/api/ports')
+  end
+
   def delete(id, files: false)
     target = uri("/api/items/#{id}")
     target.query = URI.encode_www_form(delete_files: 1) if files
@@ -188,6 +194,15 @@ Hiiro.run(*ARGV, plugins: [Pins]) {
     matching_items(opts, limit: count).each { |item| puts item_label(item) }
   }
 
+  add_subcmd(:make) { |*args|
+    Dir.chdir DESKTOP_DIR
+    system 'wails3', 'package' 
+  }
+
+  add_subcmd(:run) { |*args|
+    system 'open', APP_PATH
+  }
+
   add_subcmd(:open) { |*args|
     opts = open_opts.parse(args)
     if opts.args.empty? && !opts.html && !opts.md && !opts.all
@@ -245,4 +260,27 @@ Hiiro.run(*ARGV, plugins: [Pins]) {
   add_subcmd(:path) { |*_args|
     puts DOCS_DIR
   }
+
+  add_subcmd(:ports) { |*args|
+    json = args.include?('--json')
+    snapshot = API.ports
+    if json
+      next puts JSON.pretty_generate(snapshot)
+    end
+    ports = snapshot.fetch('ports', [])
+    if ports.empty?
+      next puts('No TCP listeners found.')
+    end
+    puts format('%-7s %-15s %-18s %-10s %s', 'PORT', 'BIND', 'PROCESS', 'UPTIME', 'DIRECTORY / HERDR / AI')
+    ports.each do |port|
+      herdr = port['herdr']
+      ai = port['ai']
+      herdr_label = herdr ? "#{herdr['workspace_label'] || herdr['workspace_id']} #{herdr['pane_id']}#{herdr['match'] == 'cwd' ? ' ~' : ''}" : '-'
+      ai_label = ai&.fetch('session', nil) ? "#{ai['kind']} #{ai['session'][0, 8]}…" : (ai&.fetch('kind', nil) || '-')
+      uptime = port['elapsed'] && !port['elapsed'].empty? ? port['elapsed'] : '-'
+      puts format('%-7s %-15s %-18s %-10s %s', port['port'], port['host'], "#{port['command']}##{port['pid']}", uptime, port['cwd'].to_s)
+      puts "         herdr: #{herdr_label}   ai: #{ai_label}"
+    end
+    warn "herdr unavailable: #{snapshot.fetch('warnings', []).join('; ')}" if snapshot['herdr_available'] == false
+  }
 }

data/bin/h-link

@@ -22,55 +22,8 @@ class LinkManager
     'created_at' => Time.now.iso8601,
   }
 
-  class Link
-    attr_accessor :url, :description, :shorthand, :created_at
-
-    def initialize(url:, description: '', shorthand: nil, created_at: Time.now.iso8601)
-      @url = url
-      @description = description
-      @shorthand = shorthand
-      @created_at = created_at
-    end
-
-    def self.from_hash(hash)
-      new(
-        url: hash['url'],
-        description: hash['description'] || '',
-        shorthand: hash['shorthand'],
-        created_at: hash['created_at'] || Time.now.iso8601
-      )
-    end
-
-    def to_h
-      {
-        'url' => @url,
-        'description' => @description,
-        'shorthand' => @shorthand,
-        'created_at' => @created_at
-      }
-    end
-
-    def to_yaml
-      to_h.to_yaml
-    end
-
-    def matches?(*terms)
-      searchable = [
-        @url,
-        @description,
-        @shorthand
-      ].compact.join(' ').downcase
-
-      terms.all? { |term| searchable.downcase.include?(term.downcase) }
-    end
-
-    def display_string(index = nil)
-      num = index ? "#{(index + 1).to_s.rjust(3)}." : ""
-      shorthand_str = @shorthand ? " [#{@shorthand}]" : ""
-      desc_str = @description.to_s.empty? ? "" : " - #{@description}"
-      "#{num}#{shorthand_str} #{@url}#{desc_str}".strip
-    end
-  end
+  # Shared representation with the DB model; YAML rows load as unsaved instances.
+  Link = Hiiro::Link
 
   attr_reader :links_file
 
@@ -172,11 +125,11 @@ class LinkManager
   end
 
   def extract_placeholders(url)
-    url.scan(/\{(\w+)\}/).flatten
+    Hiiro::URLTemplate.new(url).placeholders
   end
 
   def has_placeholders?(url)
-    !extract_placeholders(url).empty?
+    Hiiro::URLTemplate.new(url).placeholders?
   end
 
   def prompt_for_placeholder_values(url, link=nil)
@@ -212,13 +165,7 @@ class LinkManager
   end
 
   def substitute_placeholders(url, values)
-    result = url.dup
-    values.each do |key, value|
-      # Replace spaces with + for URL encoding
-      encoded_value = value.to_s.gsub(' ', '+')
-      result.gsub!("{#{key}}", encoded_value)
-    end
-    result
+    Hiiro::URLTemplate.new(url, values: values).url
   end
 
   def find_link_by_ref(ref, links)