hiiro 0.1.378 → 0.1.380

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bc8c7a68d7b0fc2d7d6182b1d307978ba4ed185d4b6162800821ef12c8fa5d4e
-  data.tar.gz: 3708447b7e35a09e59deb4cc570a770619054c299852e3ead032f6240180cfcf
+  metadata.gz: f16b6af02e89f46207b5e15d23e5e112413036a2da29ff1257cc5fec2025a655
+  data.tar.gz: 1b16f6ecf825bddf0ee1672710b09c31bac6db4489158ea0de6b714446cce1cf
 SHA512:
-  metadata.gz: 0c4a5a117425f0b879607a1040d7a757b696b0b4773d8ff1cc4747a403123029217e3ec4744031ff45b14a3f5565727c8a3a2d40097a017cf8b6bcbd68b4c93f
-  data.tar.gz: 219ff3e0aa32313353c2aad202c745788d1a6327816a90b54e9b9adee90a975709c64a36ce40c7f5425510af1e979240eb213f496ddd81da151e39e4249ee550
+  metadata.gz: 54990684ed981d3387fdfa212fdcc58ad55b6ac9f5422f79644b5bdf8c48f4d29aee5cdcbf33cd887903eee970b1ebc326b3b930e4808623001ca45c59b9283d
+  data.tar.gz: aed85297b9d4c67a7634c99d37d1c6c27f387e9c1dd784f652f9c9199c48c883e2b8a12c123574acb6a57b7f6752299f4c4285b109750ae6dd45e7f6d0b173ec

data/CHANGELOG.md

@@ -10,6 +10,9 @@
 - `t path`, `t cd`, `t start`, and `t switch` accept optional `APP` argument to select a configured relative directory beneath the task root
 - APP resolves by exact name or unique case-sensitive prefix; fails when ambiguous or missing
 
+### Added
+- `t switch` / `t workspace` and `t cd` accept an optional APP positional (or `--app`) resolving through the apps registry by exact name or unique prefix; the workspace or pane cd targets the app directory under the task worktree, e.g. `t switch aldi cpm` opens `~/work/aldi/main/retailer-tools/content-page-migrator`
+
 ## [0.1.376] - 2026-09-14
 
 ### Changed

data/README.md

@@ -92,8 +92,11 @@ prefix or a missing current task opens the fuzzy finder; non-interactive runs fa
 
 The current task is the calling Herdr workspace, then the current directory
 inside a task home, code directory, worktree, or registered directory, then the
-task saved with `t use TASK`. `t switch TASK` focuses or creates the task
-workspace and also saves it. `t current` only prints.
+task saved with `t use TASK`. `t switch TASK [APP]` focuses or creates the task
+workspace and also saves it; APP (exact name or unique prefix from the apps
+registry) opens the workspace in that app's directory under the task worktree.
+`t cd TASK [APP]` sends the same `cd` to the calling Herdr pane. `t current`
+only prints.
 
 ```sh
 t new investigation
@@ -105,7 +108,7 @@ t show investigation
 t todo rm 42                          # an ID printed by show or todo list
 t use investigation
 t switch investigation
-t switch investigation frontend          # app name or unique prefix
+t switch investigation frontend        # open in an app directory (unique prefix)
 t switch --show
 t next . "Write the handoff"
 t start investigation frontend            # tree new + app start directory

data/bin/h-docs

@@ -1,385 +1,245 @@
 #!/usr/bin/env ruby
 
 require 'hiiro'
-begin
-  require 'hiiro/tui'
-rescue LoadError
-  require File.expand_path('~/proj/hiiro/lib/hiiro/tui')
-end
 require 'json'
-require 'time'
+require 'net/http'
+require 'uri'
 
-DOCS_DIR   = File.join(Dir.home, 'claude', 'docs')
-MDOC       = File.join(Dir.home, 'bin', 'mdoc')
-INDEX_JSON = File.join(Dir.home, 'claude', 'index.json')
-INDEX_HTML = File.join(Dir.home, 'claude', 'index.html')
+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'))
+SERVICE_LABEL = "com.#{ENV.fetch('USER')}.portfolio"
+SERVICE_DOMAIN = "gui/#{Process.uid}"
+SERVICE_TARGET = "#{SERVICE_DOMAIN}/#{SERVICE_LABEL}"
+SERVICE_PLIST = File.join(Dir.home, 'Library', 'LaunchAgents', "#{SERVICE_LABEL}.plist")
 
 ls_opts = Hiiro::Options.setup {
-  flag(:html,  short: :h, default: false, desc: 'show only .html files')
-  flag(:md,    short: :m, default: false, desc: 'show only .md files')
-  flag(:full,  short: :f, default: false, desc: 'show full absolute paths')
+  flag(:html, short: :h, default: false, desc: 'show HTML-backed documents')
+  flag(:md, short: :m, default: false, desc: 'show Markdown-backed documents')
+  flag(:full, short: :f, default: false, desc: 'show API URLs and source paths')
   option(:limit, short: :l, default: nil, desc: 'limit number of results')
+  flag(:files, default: false, desc: 'with rm, also delete the tracked source file')
 }
 
 open_opts = Hiiro::Options.setup {
-  flag(:html, short: :h, default: false, desc: 'consider only .html files')
-  flag(:md,   short: :m, default: false, desc: 'consider only .md files')
-  flag(:all,  short: :a, default: false, desc: 'open ALL matches (skip fuzzyfind)')
+  flag(:html, short: :h, default: false, desc: 'consider HTML-backed documents')
+  flag(:md, short: :m, default: false, desc: 'consider Markdown-backed documents')
+  flag(:all, short: :a, default: false, desc: 'open all matches')
 }
 
-def file_patterns(opts)
-  patterns = []
-  patterns << '*.html' if opts.html
-  patterns << '*.md'   if opts.md
-  patterns.empty? ? ['*.html', '*.md'] : patterns
-end
-
-def build_regex(filters)
-  filters = ['.*'] if filters.empty?
-  Regexp.new(filters.join(?|), Regexp::IGNORECASE)
-end
-
-def find_docs(opts)
-  re = build_regex(opts.args)
-  file_patterns(opts).flat_map { |pat| Dir[File.join(DOCS_DIR, '**', pat)] }
-    .select { |path| File.basename(path).match?(re) }
-end
-
-def display(path, opts)
-  opts.respond_to?(:full) && opts.full ? path : File.basename(path)
-end
-
-def pick_one(paths)
-  return paths.first if paths.length == 1
-  basenames = paths.map { |p| File.basename(p) }
-  choice = fuzzyfind(basenames)
-  return nil if choice.nil? || choice.strip.empty?
-  paths.find { |p| File.basename(p) == choice.strip }
-end
-
-class DocsIndex
-  Entry = Struct.new(:key, :entry, :md_path, :html_path, keyword_init: true) do
-    def in_index?
-      !entry.nil?
-    end
-
-    def has_md?
-      md_path && File.file?(md_path)
-    end
-
-    def has_html?
-      html_path && File.file?(html_path)
-    end
-
-    def basename
-      "#{key}.html"
-    end
-
-    def title
-      entry&.fetch('title', nil).to_s.empty? ? key : entry['title']
-    end
-
-    def to_s
-      basename
-    end
+class PortfolioApi
+  def initialize(base_url)
+    @base = URI(base_url)
   end
 
-  def initialize(docs_dir:, index_json:, mdoc:)
-    @docs_dir = docs_dir
-    @index_json = index_json
-    @mdoc = mdoc
-    @pending_delete_paths = []
-    @changed = false
-    load_entries
-  end
-
-  attr_reader :entries
-
-  def changed?
-    @changed
-  end
+  attr_reader :base
 
-  def rows
-    indexed = entries.each_with_index.to_h { |entry, idx| [key_for_file(entry['file']), [entry, idx]] }
-    keys = indexed.keys
-    keys += Dir[File.join(@docs_dir, '*.md')].map { |path| File.basename(path, '.md') }
-    keys += Dir[File.join(@docs_dir, '*.html')].map { |path| File.basename(path, '.html') }
-
-    keys.uniq.sort_by { |key| indexed[key] ? [0, indexed[key][1]] : [1, key.downcase] }.map do |key|
-      entry = indexed.dig(key, 0)
-      Entry.new(
-        key: key,
-        entry: entry,
-        md_path: File.join(@docs_dir, "#{key}.md"),
-        html_path: html_path_for(key, entry)
-      )
-    end
+  def items(filters = [], limit: nil)
+    query = {}
+    query['q'] = filters.join(' ') unless filters.empty?
+    query['limit'] = limit.to_i if limit
+    get('/api/items', query).fetch('items')
   end
 
-  def toggle(row)
-    if row.in_index?
-      remove(row)
-      "Marked #{row.basename} for index removal and file deletion on save"
-    elsif row.has_html?
-      add(row)
-      "Added #{row.basename} to index"
-    else
-      "Cannot add #{row.basename}: no html file exists"
-    end
+  def health
+    get('/health')
   end
 
-  def regenerate(row)
-    return 'Regenerate requires an indexed row with markdown and missing html' unless row.in_index? && row.has_md? && !row.has_html?
-
-    return "Failed to regenerate #{row.basename}" unless system(@mdoc, row.md_path)
-
-    load_entries
-    @changed = true
-    "Regenerated #{row.basename}"
+  def delete(id, files: false)
+    target = uri("/api/items/#{id}")
+    target.query = URI.encode_www_form(delete_files: 1) if files
+    request(Net::HTTP::Delete.new(target))
+    true
   end
 
-  def save
-    return true unless changed?
+  def absolute_url(path)
+    return path if path.to_s.match?(%r{\Ahttps?://})
 
-    @pending_delete_paths.uniq.each do |path|
-      File.delete(path) if path && File.file?(path)
-    end
-    File.write(@index_json, JSON.pretty_generate(entries) + "\n")
-    system(@mdoc, '--rebuild-index')
+    URI.join("#{base}/", path.to_s.sub(%r{\A/}, '')).to_s
   end
 
   private
 
-  def load_entries
-    @entries = JSON.parse(File.read(@index_json))
-  rescue Errno::ENOENT, JSON::ParserError
-    @entries = []
+  def get(path, query = {})
+    target = uri(path)
+    target.query = URI.encode_www_form(query) unless query.empty?
+    JSON.parse(request(Net::HTTP::Get.new(target)))
   end
 
-  def key_for_file(file)
-    File.basename(file.to_s, '.html')
+  def uri(path)
+    URI.join("#{base}/", path.sub(%r{\A/}, ''))
   end
 
-  def html_path_for(key, entry)
-    file = entry&.fetch('file', nil)
-    return File.join(File.dirname(@docs_dir), file) if file && !file.empty?
+  def request(message)
+    response = Net::HTTP.start(message.uri.hostname, message.uri.port, open_timeout: 2, read_timeout: 15) { |http| http.request(message) }
+    raise "Portfolio API returned #{response.code}: #{response.body}" unless response.is_a?(Net::HTTPSuccess)
 
-    File.join(@docs_dir, "#{key}.html")
+    response.body
+  rescue Errno::ECONNREFUSED, SocketError => error
+    raise "Portfolio is unavailable at #{base}: #{error.message}"
   end
+end
 
-  def html_rel_for(row)
-    "docs/#{File.basename(row.html_path)}"
-  end
+API = PortfolioApi.new(SERVER)
 
-  def add(row)
-    rel = html_rel_for(row)
-    @pending_delete_paths.reject! { |path| path == row.md_path || path == row.html_path }
-    entries.reject! { |entry| entry['file'] == rel }
-    entries.unshift(
-      'title' => title_for(row),
-      'file' => rel,
-      'date' => File.mtime(row.html_path).strftime('%Y-%m-%d'),
-      'desc' => '',
-      'ts' => Time.now.iso8601
-    )
-    row.entry = entries.first
-    @changed = true
-  end
+def source_kind?(item, opts)
+  return true unless opts.html || opts.md
 
-  def remove(row)
-    rel = html_rel_for(row)
-    entries.reject! { |entry| entry['file'] == rel || key_for_file(entry['file']) == row.key }
-    @pending_delete_paths << row.md_path
-    @pending_delete_paths << row.html_path
-    row.entry = nil
-    @changed = true
-  end
+  path = item['source_path'].to_s
+  (opts.html && path.end_with?('.html')) || (opts.md && path.end_with?('.md'))
+end
 
-  def title_for(row)
-    return row.title if row.in_index?
-    return markdown_title(row.md_path) if row.has_md?
+def matching_items(opts, limit: nil)
+  API.items(opts.args, limit: limit).select { |item| source_kind?(item, opts) }
+end
 
-    row.key.tr('-', ' ')
-  end
+def item_label(item)
+  "#{item['title']} [#{item['type']} ##{item['id']}]"
+end
 
-  def markdown_title(path)
-    File.foreach(path) do |line|
-      next unless line.start_with?('# ')
+def pick_one(items)
+  return items.first if items.length == 1
 
-      return line.sub(/^#\s+/, '').strip
-    end
+  labels = items.map { |item| item_label(item) }
+  choice = fuzzyfind(labels)
+  return nil if choice.nil? || choice.strip.empty?
 
-    File.basename(path, '.md').tr('-', ' ')
-  end
+  items.find { |item| item_label(item) == choice.strip }
 end
 
-class DocsIndexTui < Hiiro::Tui::ListScreen
-  def initialize(index:)
-    @index = index
-    @message = 'space toggle index/files  r regenerate missing html  enter save/rebuild  q cancel'
-    super(items: index.rows, empty_message: 'No docs found.')
-  end
+def open_item(item)
+  system('open', API.absolute_url(item['href']))
+end
 
-  def handle_key(key)
-    case key
-    when ' '
-      @message = @index.toggle(items[cursor])
-      refresh
-    when 'r'
-      @message = @index.regenerate(items[cursor])
-      refresh
-    when :enter
-      return @index.save
-    else
-      super
-    end
-  end
+def service_loaded?
+  system('launchctl', 'print', SERVICE_TARGET, out: File::NULL, err: File::NULL)
+end
 
-  def header_lines
-    [
-      'h-docs tui',
-      'I=index entry  M=markdown file  H=html file',
-      @message,
-    ]
+def start_service
+  if service_loaded?
+    system('launchctl', 'kickstart', SERVICE_TARGET)
+  else
+    system('launchctl', 'bootstrap', SERVICE_DOMAIN, SERVICE_PLIST)
   end
+end
 
-  def footer_lines
-    ["Showing #{top + 1}-#{top + visible_items.length} of #{items.length} docs"]
-  end
+def stop_service
+  return puts('Portfolio is not loaded.') unless service_loaded?
 
-  def format_row(row, current, line_cols)
-    prefix = current ? '> ' : '  '
-    indicators = [
-      row.in_index? ? 'I' : '-',
-      row.has_md? ? 'M' : '-',
-      row.has_html? ? 'H' : '-',
-    ].join
-    fixed = "#{prefix}#{indicators} "
-    text_cols = [line_cols - fixed.length, 1].max
-    text = (fixed + visible_text(row.basename, text_cols, horizontal_offset)).ljust(line_cols)
-    style =
-      if current
-        "\e[7m"
-      elsif row.in_index? && row.has_md? && !row.has_html?
-        "\e[33m"
-      else
-        "\e[0m"
-      end
+  system('launchctl', 'bootout', SERVICE_TARGET)
+end
 
-    "#{style}#{text}\e[0m\e[K"
+def restart_service
+  if service_loaded?
+    system('launchctl', 'kickstart', '-k', SERVICE_TARGET)
+  else
+    start_service
   end
+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?
+Hiiro.run(*ARGV, plugins: [Pins]) {
+  add_subcmd(:setup, :install) { |*_args|
+    installer = File.join(PROJECT_ROOT, 'bin', 'install')
+    abort "Installer not found: #{installer}\nSet PORTFOLIO_HOME to the project directory." unless File.executable?(installer)
+    exit($?.exitstatus || 1) unless system(installer)
+  }
 
-    fixed_width = 6
-    remaining_cols = [line_cols - fixed_width, 1].max
-    min_visible_chars = [5, remaining_cols].min
-    longest = visible.map { |row| row.basename.length }.max || 0
+  add_subcmd(:start) { |*_args|
+    abort "LaunchAgent not installed. Run: h-docs setup" unless File.file?(SERVICE_PLIST)
+    exit($?.exitstatus || 1) unless start_service
+    puts 'Portfolio started.'
+  }
 
-    [longest - min_visible_chars, 0].max
-  end
+  add_subcmd(:stop) { |*_args|
+    stop_service
+  }
 
-  private
+  add_subcmd(:restart) { |*_args|
+    abort "LaunchAgent not installed. Run: h-docs setup" unless File.file?(SERVICE_PLIST)
+    exit($?.exitstatus || 1) unless restart_service
+    puts 'Portfolio restarted.'
+  }
 
-  def refresh
-    @items = @index.rows
-    if items.empty?
-      @cursor = 0
-      @top = 0
-      return :continue
+  add_subcmd(:status) { |*_args|
+    if service_loaded?
+      system('launchctl', 'print', SERVICE_TARGET)
+    else
+      warn 'Portfolio is not loaded. Run: h-docs start'
+      exit 1
     end
+  }
 
-    @cursor = [[cursor, 0].max, items.length - 1].min
-    @top = [[top, 0].max, @cursor].min
-    :continue
-  end
-end
-
-Hiiro.run(*ARGV, plugins: [Pins]) {
   add_subcmd(:ls) { |*args|
-    opts  = ls_opts.parse(args)
-    paths = find_docs(opts).sort
-    paths = paths.last(opts.limit.to_i) if opts.limit
-    paths.each { |p| puts display(p, opts) }
+    opts = ls_opts.parse(args)
+    matching_items(opts, limit: opts.limit).each do |item|
+      if opts.full
+        puts [API.absolute_url(item['href']), item['source_path']].compact.join("\t")
+      else
+        puts item_label(item)
+      end
+    end
   }
 
   add_subcmd(:recent) { |*args|
-    opts    = ls_opts.parse(args)
-    numeric = opts.args.find { |a| a =~ /^\d+$/ }
-    n       = (opts.limit || numeric || 10).to_i
-    filters = opts.args.reject { |a| a =~ /^\d+$/ }
-    re      = build_regex(filters)
-
-    paths = file_patterns(opts).flat_map { |pat| Dir[File.join(DOCS_DIR, '**', pat)] }
-      .select { |p| File.basename(p).match?(re) }
-      .sort_by { |p| -File.mtime(p).to_i }
-      .first(n)
-
-    paths.each { |p| puts display(p, opts) }
+    opts = ls_opts.parse(args)
+    numeric = opts.args.find { |arg| arg.match?(/^\d+$/) }
+    count = (opts.limit || numeric || 10).to_i
+    opts.args.delete(numeric) if numeric
+    matching_items(opts, limit: count).each { |item| puts item_label(item) }
   }
 
   add_subcmd(:open) { |*args|
-    opts  = open_opts.parse(args)
-    paths = find_docs(opts)
-    next puts('No matching docs.') if paths.empty?
+    opts = open_opts.parse(args)
+    if opts.args.empty? && !opts.html && !opts.md && !opts.all
+      next system('open', SERVER)
+    end
+
+    items = matching_items(opts)
+    next puts('No matching items.') if items.empty?
 
-    targets = opts.all ? paths : [pick_one(paths)].compact
-    targets.each { |t| system('open', t) }
+    (opts.all ? items : [pick_one(items)].compact).each { |item| open_item(item) }
   }
 
   add_subcmd(:vim) { |*args|
-    opts  = ls_opts.parse(args)
-    paths = find_docs(opts).sort
-    next puts('No matching docs.') if paths.empty?
+    opts = ls_opts.parse(args)
+    paths = matching_items(opts).filter_map { |item| item['source_path'] if File.file?(item['source_path'].to_s) }
+    next puts('No matching local sources.') if paths.empty?
+
     edit_files(*paths)
   }
 
   add_subcmd(:cat) { |*args|
-    opts  = ls_opts.parse(args)
-    paths = find_docs(opts).sort
-    next puts('No matching docs.') if paths.empty?
-
-    paths.each do |p|
-      puts "===== #{File.basename(p)} ====="
-      puts File.read(p)
-      puts
-    end
+    opts = ls_opts.parse(args)
+    paths = matching_items(opts).filter_map { |item| item['source_path'] if File.file?(item['source_path'].to_s) }
+    next puts('No matching local sources.') if paths.empty?
+
+    paths.each { |path| puts "===== #{File.basename(path)} =====", File.read(path), '' }
   }
 
   add_subcmd(:rm) { |*args|
-    opts  = ls_opts.parse(args)
-    paths = find_docs(opts)
-    next puts('No matching docs.') if paths.empty?
-
-    target = pick_one(paths)
-    next unless target
-    File.delete(target)
-    puts "Removed: #{target}"
+    opts = ls_opts.parse(args)
+    items = matching_items(opts)
+    next puts('No matching items.') if items.empty?
+
+    item = pick_one(items)
+    next unless item
+
+    API.delete(item['id'], files: opts.files)
+    suffix = opts.files ? ' and deleted tracked source file' : ''
+    puts "Removed from Portfolio#{suffix}: #{item_label(item)}"
   }
 
   add_subcmd(:count) { |*_args|
-    html = Dir[File.join(DOCS_DIR, '**', '*.html')].count
-    md   = Dir[File.join(DOCS_DIR, '**', '*.md')].count
-    puts "html:  #{html}"
-    puts "md:    #{md}"
-    puts "total: #{html + md}"
+    puts "items: #{API.health.fetch('items')}"
   }
 
-  add_subcmd(:index) { |*_args|
-    system('open', INDEX_HTML)
+  add_subcmd(:index, :tui) { |*_args|
+    system('open', SERVER)
   }
 
   add_subcmd(:reindex, :rebuild) { |*_args|
-    exit($?.exitstatus || 1) unless system(MDOC, '--rebuild-index')
-  }
-
-  add_subcmd(:tui) { |*_args|
-    index = DocsIndex.new(docs_dir: DOCS_DIR, index_json: INDEX_JSON, mdoc: MDOC)
-    saved = DocsIndexTui.new(index: index).run
-    puts(saved ? 'Saved docs index.' : 'Canceled docs index changes.')
+    status = API.health
+    puts "Portfolio search index is live (#{status.fetch('items')} items)."
   }
 
   add_subcmd(:path) { |*_args|

data/bin/hh

@@ -0,0 +1,50 @@
+#!/usr/bin/env ruby
+
+require 'hiiro'
+
+Hiiro.run do
+  add_cmd(:ls) do
+    cmd = 'herdr', 'session', 'list', *opts.original_args
+    temp = Tempfile.new('asdf')
+    system(*cmd)
+  end
+
+  add_cmd(:switch, :start) do
+    cmd = 'herdr', 'session', 'list'
+    temp = Tempfile.new('asdf')
+    system(*cmd, out: temp.path)
+
+    lines = File.readlines(temp.path, chomp: true)
+
+    sessions = lines.filter_map.with_index{|x, i| next if i == 0; [x, x.split(/\s+/, 2).first] }.to_h
+
+    ses = 
+      if opts.args.empty?
+        fuzzyfind_from_map(sessions)
+      else
+        opts.args.first
+      end
+
+    use = sessions.values.find{|ss| ss.start_with?(ses) }
+
+    system('herdr', '--session', use)
+  end
+
+  add_cmd(:kill, :stop, :rm, :remove) do
+    tmp = Tempfile.new 'asdf'
+    result = system 'herdr', 'session' ,'stop', *opts.args, err: tmp.path
+
+    if result
+      result = system 'herdr', 'session' ,'delete', *opts.args 
+    else
+      reason = File.read tmp.path
+      if reason[/running/]
+        result = system 'herdr', 'session' ,'delete', *opts.args 
+      end
+    end
+  end
+
+  add_default do |*args|
+    system 'herdr', *args
+  end
+end

data/docs/t.md

@@ -95,7 +95,7 @@ t doc open [TASK] [NAME]
 | `t path [TASK] [APP]` | Start directory, optionally beneath the configured relative directory for APP |
 | `t branch [TASK]` | Worktree branch or `(detached)` |
 | `t sh [TASK] [CMD...]` | Changes to the start directory and execs a shell or CMD |
-| `t cd [TASK] [APP]` | Sends `cd` to the calling Herdr pane |
+| `t cd [TASK] [APP]` | Sends `cd` to the calling Herdr pane; APP narrows to a registry app directory under the task worktree |
 
 Worktree creation is `Hiiro::TaskManager#create_tree`, shared with the legacy `h task start` code path.
 
@@ -104,7 +104,7 @@ APP resolves against configured Hiiro apps by exact name or unique case-sensitiv
 ## Herdr workspaces, tabs, and panes
 
 ```text
-t switch [TASK] [APP] [--directory PATH] [--show]      alias: workspace
+t switch [TASK] [APP] [--directory PATH] [--show]   alias: workspace
 t tab ls [TASK]
 t tab new [TASK] [LABEL] [--directory PATH] [--command COMMAND]
 t tab open [TASK] [ID|LABEL]
@@ -117,6 +117,10 @@ t pane split [TASK] ID|LABEL [--direction right|down] [--directory PATH] [--comm
 
 These require a running Herdr server. The workspace label is the task session or name with `.` replaced by `_`. For a task, optional APP selects its configured relative directory when creating the workspace; when the workspace already exists, `switch` focuses it and sends `cd` to its focused pane. APP and `--directory` cannot be combined. `switch` also accepts the name of a live Herdr workspace that belongs to no task, exactly or by unique prefix, and focuses it; APP is invalid for loose workspaces and panes. A task with the same name wins. An exact pane ID such as `w6:p2` focuses that pane, and the picker lists every live pane with its directory and foreground command. When the name is ambiguous, or no task or context is given, a terminal gets a fuzzy finder over tasks and loose workspaces, with duplicate workspace names numbered in the label only. Commands that jump somewhere never assume the current task: `t switch`, `t tab open`, and `t pane open` with no task open the picker instead (or fail when stdin is not a terminal); use `.` explicitly for the current task.
 
+### App directories
+
+`t switch TASK APP` and `t cd TASK APP` accept APP as an exact name or unique prefix from the apps registry (`Hiiro::AppRecord`); `--app APP` is the flag form. The workspace opens (or the pane cds) into the app's directory under the task worktree, e.g. with `aldi` registered as `retailer-tools/content-page-migrator`, `t switch aldi cpm` opens `~/work/aldi/main/retailer-tools/content-page-migrator`. An ambiguous prefix is an error; APP only applies to task workspaces, not panes or loose workspaces.
+
 ## Native AI sessions
 
 `t omp [TASK] [ARGS...]`, `t codex` / `cdx`, and `t claude` / `cld` create a new focused tab in the task workspace, creating the workspace if needed, and run the native tool with ARGS forwarded verbatim. A leading argument that is a prefix of `resume` turns into the tool's native resume flag; bare `resume` with exactly one running pane of that tool focuses it instead.

data/lib/hiiro/task_cli.rb

@@ -63,6 +63,18 @@ class Hiiro
         lookup_task(reference) || raise(Error, "Task not found: #{reference}; run t new #{reference}")
       end
 
+      # [name, relative_path] from the apps registry: exact name wins, else a
+      # unique prefix; ambiguity and no-match are errors.
+      def lookup_app!(reference)
+        apps = Hiiro::AppRecord.all_as_hash
+        raise Error, 'No apps are configured' if apps.empty?
+        return [reference, apps[reference]] if apps[reference]
+        found = Hiiro::Matcher.by_prefix(apps.keys.sort, reference).matches.map(&:item)
+        raise Error, "No app matches #{reference}" if found.empty?
+        raise Error, "Ambiguous app #{reference}: #{found.join(', ')}" unless found.one?
+        [found.first, apps[found.first]]
+      end
+
       # Current task from Herdr, directory, or the saved pin. With no context at all,
       # a TTY gets the fuzzy finder over every task; ambiguous or stale context still fails.
       def current_task
@@ -469,6 +481,26 @@ class Hiiro
           herdr
         end
       end
+      # App reference (positional or --app) resolves through the apps registry
+      # under the task worktree; explicit param wins over the option.
+      def start_directory(task, app: nil)
+        app = opts&.fetch(:app) if app.nil?
+        path = opts&.fetch(:directory) || (app && app_directory(task, app)) || code_directory(task) || ensure_home(task)
+        existing_path(path, directory: true)
+      end
+
+      # Registry app directory under the task worktree.
+      def app_directory(task, reference)
+        _name, relative = lookup_app!(reference)
+        root = code_directory(task)
+        raise Error, "#{task.name} has no worktree; run t tree new #{task.name} first" unless root
+        File.join(root, relative)
+      end
+
+      def open_workspace(task, save:, app: nil)
+        open_task_workspace(task, start_directory(task, app: app))
+        save_current(task) if save
+      end
 
       def workspace_for(task, required: true)
         label = workspace_label(task)
@@ -480,29 +512,6 @@ class Hiiro
         matches.first
       end
 
-      def app_directory(path, app_name)
-        return path unless app_name
-        result = Hiiro::Matcher.new(Hiiro::AppRecord.all, :name).by_prefix(app_name)
-        app = result.resolved&.item
-        if !app && result.ambiguous?
-          raise Error, "Ambiguous app #{app_name}: #{result.matches.map { |match| match.item.name }.join(', ')}"
-        end
-        raise Error, "App not found: #{app_name}" unless app
-        File.join(path, app.path)
-      end
-
-      def start_directory(task, app_name = nil)
-        path = opts&.fetch(:directory)
-        raise Error, 'Use an app or --directory, not both' if path && app_name
-        path ||= code_directory(task) || ensure_home(task)
-        existing_path(app_directory(path, app_name), directory: true)
-      end
-
-      def open_workspace(task, save:, app_name: nil)
-        open_task_workspace(task, start_directory(task, app_name), chdir: !app_name.nil?)
-        save_current(task) if save
-      end
-
       # Focus the task workspace or create it at directory. With optional: true,
       # a stopped Herdr prints a hint instead of failing (used after worktree changes).
       def open_task_workspace(task, directory, optional: false, chdir: false)
@@ -556,51 +565,47 @@ class Hiiro
         puts pane_line(pane)
       end
 
-      # [target, explicit, app_name]. A task wins over a workspace with the same name.
+      # [target, explicit, rest]. A task wins over a workspace with the same name.
+      # The first positional names the target; any remaining positional is the app.
       def switch_target(args)
         args = args.dup
-        return [lookup_task!(opts.task), true, single(args, optional: true)] if opts.task
-        return [pick_switch_target(Hiiro::TaskRecord.all_as_list, loose_workspaces), true, single(args, optional: true)] if opts.find
-        first = args.first
+        first = args.shift
+        rest = args
+        if opts.task || opts.find
+          # Flag forces the target, so the first positional is the app.
+          app = [first].compact
+          no_args!(rest)
+          return [lookup_task!(opts.task), true, app] if opts.task
+          return [pick_switch_target(Hiiro::TaskRecord.all_as_list, loose_workspaces), true, app] if opts.find
+        end
+        no_args!(rest.drop(1))
         if first && first != '.' && !first.start_with?('-')
-          args.shift
-          app_name = single(args, optional: true)
           tasks = Hiiro::TaskRecord.all_as_list
           workspaces = loose_workspaces
           exact = tasks.find { |task| task.name == first }
-          return [exact, true, app_name] if exact
+          return [exact, true, rest] if exact
           pane = live_panes.values.flatten.find { |candidate| candidate.id == first }
-          raise Error, 'An app applies only to task workspaces' if pane && app_name
-          return [pane, false, nil] if pane
+          return [pane, false, rest] if pane
           exact_ws = workspaces.select { |workspace| workspace.name == first }
-          if exact_ws.one?
-            raise Error, 'An app applies only to task workspaces' if app_name
-            return [exact_ws.first, false, nil]
-          end
+          return [exact_ws.first, false, rest] if exact_ws.one?
           task_matches = tasks.select { |task| task.name.start_with?(first) }
           ws_matches = exact_ws.any? ? exact_ws : workspaces.select { |workspace| workspace.name.start_with?(first) }
-          return [task_matches.first, true, app_name] if task_matches.one? && ws_matches.empty?
-          if ws_matches.one? && task_matches.empty?
-            raise Error, 'An app applies only to task workspaces' if app_name
-            return [ws_matches.first, false, nil]
-          end
+          return [task_matches.first, true, rest] if task_matches.one? && ws_matches.empty?
+          return [ws_matches.first, false, rest] if ws_matches.one? && task_matches.empty?
           raise Error, "No task or workspace matches #{first}" if task_matches.empty? && ws_matches.empty?
           names = (task_matches.map(&:name) + ws_matches.map { |w| "#{w.name} (workspace)" }).join(', ')
           raise Error, "Ambiguous #{first}: #{names}" unless $stdin.tty?
           target = pick_switch_target(task_matches, ws_matches, panes: [])
-          raise Error, 'An app applies only to task workspaces' if app_name && !target.is_a?(Hiiro::TaskRecord)
-          return [target, target.is_a?(Hiiro::TaskRecord), app_name]
+          return [target, target.is_a?(Hiiro::TaskRecord), rest]
         end
+        no_args!(rest)
         if first == '.'
-          args.shift
-          app_name = single(args, optional: true)
-          return [Hiiro::CurrentTask.new(herdr: -> { herdr_client }, pin: true).resolve!, false, app_name]
+          return [Hiiro::CurrentTask.new(herdr: -> { herdr_client }, pin: true).resolve!, false, rest]
         end
-        no_args!(args)
         # Jumping somewhere never assumes the current task: pick a destination.
         raise Error, 'Name a task, workspace, or pane to switch to, or use . for the current task' unless $stdin.tty?
         target = pick_switch_target(Hiiro::TaskRecord.all_as_list, loose_workspaces)
-        [target, target.is_a?(Hiiro::TaskRecord), nil]
+        [target, target.is_a?(Hiiro::TaskRecord), rest]
       end
 
       def require_picker!(what)
@@ -707,10 +712,10 @@ class Hiiro
         command.empty? ? exec(ENV['SHELL'] || 'zsh') : exec(*command)
       end
 
-      def cd_to(task, app_name = nil)
+      def cd_to(task, app: nil)
         pane = ENV['HERDR_PANE_ID']
         raise Error, 'Not running inside a Herdr pane' unless pane
-        check_result(client.run_in_pane(pane, "cd #{start_directory(task, app_name).shellescape}"))
+        check_result(client.run_in_pane(pane, "cd #{start_directory(task, app: app).shellescape}"))
       end
 
       def show_workspace(task)
@@ -850,45 +855,36 @@ class Hiiro
           end
         end
 
-        add_cmd(:path, args: ['task?', 'app?'], opts: TASK_OPTIONS) do
-          task, rest = take_task(opts.args)
-          puts start_directory(task, single(rest, optional: true))
-        end
-        add_cmd(:branch, args: ['task?'], opts: TASK_OPTIONS) { puts current_branch(take_task_only(opts.args)) }
-        add_cmd(:cd, args: ['task?', 'app?'], opts: TASK_OPTIONS) do
-          task, rest = take_task(opts.args)
-          cd_to(task, single(rest, optional: true))
-        end
-        add_cmd(:sh, args: ['task?', 'command...'], passthrough: true) do
-          task, rest = take_task(args, options: nil)
-          run_shell(task, rest)
-        end
-
         add_option :directory, desc: 'Existing start directory'
-        add_option :app, desc: 'App directory to open in the workspace'
-        add_option :sparse, short: :s, desc: 'Sparse checkout group (repeatable)', multi: true
-        add_cmd(:start, args: %i[name app?], opts: [*TASK_OPTIONS, :app, :sparse]) do
-          if opts.task
-            new_tree([lookup_task!(opts.task).name, *opts.args], opts.app, opts.sparse)
-          elsif opts.find
-            new_tree([pick_task(Hiiro::TaskRecord.all_as_list).name, *opts.args], opts.app, opts.sparse)
-          else
-            new_tree(opts.args, opts.app, opts.sparse)
-          end
-        end
-        add_cmd(:switch, :workspace, args: ['task-or-workspace?', 'app?'], opts: [*TASK_OPTIONS, :directory, :show]) do
-          target, explicit, app_name = switch_target(opts.args)
+        add_option :app, desc: 'Registry app directory under the task worktree'
+        add_cmd(:switch, :workspace, args: ['task-or-workspace?', 'app?'], opts: [*TASK_OPTIONS, :directory, :app, :show]) do
+          target, explicit, rest = switch_target(opts.args)
+          app = opts.app || rest.first
           if target.is_a?(Hiiro::Herdr::Pane)
             raise Error, '--show applies to task workspaces' if opts.show
+            raise Error, 'An APP only applies to task workspaces' if app
             focus_pane_target(target)
           elsif target.is_a?(Hiiro::Herdr::Workspace)
             raise Error, '--show applies to task workspaces' if opts.show
+            raise Error, 'An APP only applies to task workspaces' if app
             check_result(client.focus_workspace(target.id))
             puts target
           else
-            opts.show ? show_workspace(target) : open_workspace(target, save: explicit, app_name: app_name)
+            opts.show ? show_workspace(target) : open_workspace(target, save: explicit, app: app)
           end
         end
+        add_cmd(:path, args: ['task?'], opts: TASK_OPTIONS) { puts start_directory(take_task_only(opts.args)) }
+        add_cmd(:branch, args: ['task?'], opts: TASK_OPTIONS) { puts current_branch(take_task_only(opts.args)) }
+        add_cmd(:cd, args: ['task?', 'app?'], opts: TASK_OPTIONS) do
+          task, rest = take_task(opts.args)
+          no_args!(rest.drop(1))
+          cd_to(task, app: rest.first)
+        end
+
+        add_cmd(:sh, args: ['task?', 'command...'], passthrough: true) do
+          task, rest = take_task(args, options: nil)
+          run_shell(task, rest)
+        end
 
         [%w[omp], %w[codex cdx], %w[claude cld]].each do |names|
           add_cmd(*names, args: ['task?', 'cli-args...'], passthrough: true) do

data/lib/hiiro/version.rb

@@ -1,4 +1,4 @@
 class Hiiro
-  VERSION = "0.1.378"
+  VERSION = "0.1.380"
   SUPPORTED_RUBY_VERSION = ">= 3.2.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: hiiro
 version: !ruby/object:Gem::Version
-  version: 0.1.378
+  version: 0.1.380
 platform: ruby
 authors:
 - Joshua Toyota
@@ -219,6 +219,7 @@ files:
 - bin/h-wtree
 - bin/h-xxserve
 - bin/h-zosubtask
+- bin/hh
 - bin/t
 - bin/tt
 - demo.sh