hiiro 0.1.376 → 0.1.377

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a8a343767837132ea50864926898caf5fcbc01788bbfadd351f426fe6e7bc770
-  data.tar.gz: e8274d74d87414a087f45f3bf65584ecec9ffd999d48ca5328591e729babdf9e
+  metadata.gz: 6f85065ec7cb2c8b4fe08aba7d0692ef740963b272035324d57befbf471e9e23
+  data.tar.gz: 26745904bd4837c6b3fc2a4bf3372a2715c719af23c975b1dbcf7ad1445f430c
 SHA512:
-  metadata.gz: 46b9f915a21b4c84a14971b5b30aa1a6f48f1507b049eb4ff59546e627c9eccb84cc0ac8863591dc50ab4f4ae4afff3af45c599c430751bcc3b1b7bb3e81fefc
-  data.tar.gz: 45c777ea183fbc5eb26de72be4b7a4e303423c76f0ca99431b492d6615e82d296932cddb17c46f7f2ea6dabdd936e2762290d9a81375dc5d82413f35d770fabe
+  metadata.gz: bcee60b2999a7acddb1918f05184ba2f84055f59440bec14b323d7a328c685cbf076a66d8c8b9753c91c92720213169c7d14b705946cf934e7382966953e9462
+  data.tar.gz: 024bb62f15a76b36e01e102f76d2a505dd78f2db8079f19fce7d3c7e19bd3d892aac31ab45db24a5b1ecc36ef631982fa40a64b6ede114693bb7b5664f5ea8f4

data/AGENTS.md

@@ -0,0 +1,544 @@
+## 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.
+
+## Development Commands
+
+```bash
+# Edit the main h script
+h edit
+
+# List available subcommands
+h
+
+# Syntax check Ruby files
+ruby -c bin/h
+ruby -c plugins/*.rb
+```
+
+
+Tests are organized under `test/`:
+- `test/hiiro/` - Core library tests (Matcher, Options, Shell, Fuzzyfind, Todo, etc.)
+- `test/plugins/` - Plugin tests (Pins, Tasks, Notify, Project)
+- `test/bin/` - Bin file tests using `Hiiro::TestHarness`
+
+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.
+
+## Architecture
+
+### Core Components (bin/h)
+
+The `Hiiro` class is the main entry point with these nested classes:
+
+- **`Runners`** - Discovers executables matching `h-*` in PATH and manages inline subcommands. Implements exact and prefix-based matching.
+- **`Runners::Bin`** - Represents external executables found in PATH
+- **`Runners::Subcommand`** - Represents inline subcommands registered via blocks
+- **`Args`** - Parses single-dash flags (`-abc` becomes flags `a`, `b`, `c`)
+- **`Config`** - Manages `~/.config/hiiro/` directory structure
+
+### Subcommand Resolution Flow
+
+1. `Hiiro.init()` parses first arg as subcommand name
+2. `Runners` searches for exact match in subcommands and PATH executables
+3. If no exact match, tries prefix matching (abbreviations)
+4. Ambiguous matches show help with possible options
+
+### Plugin System
+
+Plugins are Ruby modules with a `self.load(hiiro)` method:
+
+```ruby
+module MyPlugin
+  def self.load(hiiro)
+    # Add methods to hiiro instance
+    hiiro.instance_eval do
+      def my_helper; end
+    end
+
+    # Register subcommands
+    hiiro.add_subcmd(:mycmd) { |*args| ... }
+  end
+end
+```
+
+Plugins auto-load from `~/.config/hiiro/plugins/`. Load order matters when plugins depend on each other (e.g., Task and Project depend on Tmux).
+
+### Global Values Pattern
+
+Values passed to `Hiiro.run()` are available in subcommand handlers:
+
+```ruby
+Hiiro.run(*ARGV, cwd: Dir.pwd) do
+  add_subcmd(:pwd) { |*args|
+    cwd = get_value(:cwd)
+    puts cwd
+  }
+end
+```
+
+## Creating Subcommands
+
+There are two ways to add subcommands to Hiiro:
+
+### 1. External Bin File (Preferred)
+
+Create a new executable `bin/h-<name>` that uses `Hiiro.run`:
+
+```ruby
+#!/usr/bin/env ruby
+require 'hiiro'
+
+Hiiro.run(*ARGV, plugins: [:Tasks]) {
+  add_subcmd(:list) {
+    puts "Listing items..."
+  }
+
+  add_subcmd(:add) { |name, path=nil|
+    puts "Adding #{name} at #{path}"
+  }
+
+  add_subcmd(:remove) { |name=nil|
+    if name.nil?
+      puts "Usage: h mycommand remove <name>"
+      next
+    end
+    puts "Removed #{name}"
+  }
+}
+```
+
+This creates commands like `h mycommand list`, `h mycommand add foo /path`.
+
+### 2. Nested Subcommands via build_hiiro
+
+For complex command hierarchies with shared state, create a nested Hiiro instance:
+
+```ruby
+def self.add_subcommands(hiiro)
+  hiiro.add_subcmd(:task) do |*args|
+    tm = TaskManager.new(hiiro, scope: :task)
+    build_hiiro(hiiro, tm).run
+  end
+end
+
+def self.build_hiiro(parent_hiiro, tm)
+  bin_name = [parent_hiiro.bin, parent_hiiro.subcmd || ''].join('-')
+
+  Hiiro.run(bin_name:, args: parent_hiiro.args) do
+    add_subcmd(:list) { tm.list }
+    add_subcmd(:start) { |name| tm.start_task(name) }
+    add_subcmd(:switch) { |name=nil|
+      name ||= tm.select_task_interactive
+      tm.switch_to_task(tm.task_by_name(name))
+    }
+  end
+end
+```
+
+This pattern:
+- Passes remaining args from parent to child via `args: parent_hiiro.args`
+- Allows shared state (like `tm`) across all nested subcommands
+- Creates commands like `h task list`, `h task start foo`
+
+## Library Components (lib/)
+
+The `lib/hiiro.rb` file and `lib/hiiro/` directory contain the core framework classes:
+
+### Hiiro (lib/hiiro.rb)
+
+Main entry point with class methods:
+- `Hiiro.run(*ARGV, plugins: [...]) { ... }` - Initialize and run immediately
+- `Hiiro.init(*ARGV, plugins: [...]) { ... }` - Initialize without running (returns hiiro instance).  **NEVER USE THIS** without a good reason, always favor `Hiiro.run`
+
+Instance methods available in subcommand blocks:
+- `git` - Returns `Hiiro::Git` instance for git operations
+- `fuzzyfind(lines)` - Interactive selection via skim
+- `fuzzyfind_from_map(hash)` - Interactive selection returning mapped value
+- `pins` - Key-value storage per command
+- `todo_manager` - Todo item management
+- `attach_method(name, &block)` - Add methods to hiiro instance dynamically
+- `make_child(subcmd, *args)` - Create nested Hiiro for sub-subcommands (returns instance, must call `.run` manually)
+- `run_child(subcmd, *args)` - Create a nested Hiiro instance AND immediately run it (preferred over `make_child(...).run`)
+
+### Hiiro::Matcher (lib/hiiro/matcher.rb)
+
+Handles pattern matching for commands and items with prefix and substring matching:
+
+```ruby
+matcher = Hiiro::Matcher.new(items, :name)
+
+# Prefix matching - find items where name starts with pattern
+result = matcher.by_prefix("pre")
+result.match?                     # Any matches?
+result.one?                       # Exactly one match?
+result.ambiguous?                 # Multiple matches?
+result.first&.item                # Get first matching item
+result.resolved&.item             # Get exact or single match
+
+# Substring matching - find items where name contains pattern anywhere
+result = matcher.by_substring("abc")
+result.matches.map(&:item)        # All matching items
+
+# Path-based matching for hierarchical names (e.g., "task/subtask")
+result = matcher.resolve_path("t/s")
+
+# Class methods for one-off matching
+Hiiro::Matcher.by_prefix(items, "pre", key: :name)
+Hiiro::Matcher.by_substring(items, "abc", key: :name)
+```
+
+Note: `Hiiro::PrefixMatcher` is aliased to `Hiiro::Matcher` for backward compatibility.
+
+### Hiiro::Git (lib/hiiro/git.rb)
+
+Git operations wrapper with submodules for branches, worktrees, remotes, and PRs:
+
+```ruby
+git = hiiro.git
+git.root                          # Repository root path
+git.branch                        # Current branch name
+git.branches                      # List all branches
+git.worktrees                     # List all worktrees
+git.add_worktree(path, branch:)   # Create worktree
+git.move_worktree(from, to)       # Rename worktree
+git.current_pr                    # Get current PR info
+```
+
+### Hiiro::DB (lib/hiiro/db.rb)
+
+SQLite persistence layer backed by Sequel. All data is stored in `~/.config/hiiro/hiiro.db`.
+
+**Setup:** `Hiiro::DB.setup!` is called at startup — creates any missing tables, then runs a one-time YAML→SQLite migration if the DB is new.
+
+**Model registration:** Each Sequel model calls `Hiiro::DB.register(self)` so `setup!` can create its table:
+
+```ruby
+class Hiiro::MyModel < Sequel::Model(:my_table)
+  Hiiro::DB.register(self)
+
+  def self.create_table!(db)
+    db.create_table?(:my_table) do
+      primary_key :id
+      String :name, null: false
+    end
+  end
+end
+```
+
+**Dual-write:** During rollout, models write to both SQLite and YAML. Once migration is stable, call `Hiiro::DB.disable_dual_write!` to stop YAML writes.
+
+**Test isolation:** Set `ENV['HIIRO_TEST_DB'] = 'sqlite::memory:'` before requiring `hiiro` to get a clean in-memory DB per test run. Call `Hiiro::DB.setup!` after require.
+
+**`h db` subcommand:** Inspect and manage the database:
+- `h db status` — show connection info and migration state
+- `h db tables` — list all tables with row counts
+- `h db q <sql>` — run raw SQL and print results
+- `h db migrate` — re-run YAML import (if not yet migrated)
+- `h db restore` — restore YAML files from SQLite data
+
+### Hiiro::Fuzzyfind (lib/hiiro/fuzzyfind.rb)
+
+Integration with `sk` (skim) or `fzf` fuzzy finders:
+
+```ruby
+selected = Hiiro::Fuzzyfind.select(["option1", "option2", "option3"])
+# Returns selected string or nil if cancelled
+
+value = Hiiro::Fuzzyfind.map_select({ "Display 1" => "value1", "Display 2" => "value2" })
+# Shows keys, returns corresponding value
+```
+
+### Hiiro::TodoManager (lib/hiiro/todo.rb)
+
+Todo item management with task association:
+
+```ruby
+tm = Hiiro::TodoManager.new
+tm.add("Fix bug", tags: "urgent", task_info: { task_name: "feature" })
+tm.start(0)                       # Mark item as started
+tm.done(0)                        # Mark item as done
+tm.active                         # Items not done/skipped
+tm.filter_by_task("feature")      # Items for specific task
+```
+
+### Invocation Tracking (lib/hiiro/invocation.rb)
+
+Every CLI invocation is automatically recorded to SQLite via `Hiiro::Invocation` and `Hiiro::InvocationResolution`. This happens in `Hiiro.init` — no extra setup needed.
+
+**Schema:**
+- `Hiiro::Invocation` — records `bin_name`, `argv_json`, `cwd`, `invoked_at`
+- `Hiiro::InvocationResolution` — linked to an invocation; records `resolved_name`, `resolution_type` (exact/prefix/abbreviated), `subcmd`
+
+**Query recent invocations:**
+```ruby
+Hiiro::Invocation.order(Sequel.desc(:invoked_at)).limit(20).each do |inv|
+  puts "#{inv.invoked_at}  #{inv.bin_name} #{JSON.parse(inv.argv_json).join(' ')}"
+end
+```
+
+Or via `h db q`:
+```bash
+h db q "SELECT bin_name, argv_json, invoked_at FROM invocations ORDER BY invoked_at DESC LIMIT 10"
+```
+
+### Hiiro::Shell (lib/hiiro/shell.rb)
+
+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
+```
+
+### Hiiro::Options (lib/hiiro/options.rb)
+
+Argument parsing with flag and option support:
+
+```ruby
+opts = Hiiro::Options.parse(args) do
+  option(:output, short: :o, desc: "Output file")
+  option(:verbose, short: :v, type: :flag, desc: "Verbose output")
+end
+opts.output    # Value of --output or -o
+opts.verbose   # true if --verbose or -v was passed
+opts.args      # Remaining non-option arguments
+```
+
+### Hiiro::Notification (lib/hiiro/notification.rb)
+
+macOS notification wrapper using terminal-notifier:
+
+```ruby
+Hiiro::Notification.show(hiiro)   # Show notification based on hiiro.args
+# Supports: -m message, -t title, -l link, -c command, -s sound (macOS system sound name via terminal-notifier -sound; none for silent)
+```
+
+### Hiiro::Queue (lib/hiiro/queue.rb)
+
+Task queue that pipes prompts to `claude` via tmux. Tasks are markdown files with optional YAML frontmatter (`task_name`, `tree_name`, `session_name`) that flow through statuses: `wip` -> `pending` -> `running` -> `done`/`failed`.
+
+Subcommands (`h queue <subcmd>`):
+- `ls`/`list` - List all tasks with status, elapsed time, and preview
+- `status` - Detailed status with working directory info
+- `add` - Create a new prompt (opens editor or accepts stdin/args, supports `-t <task>` flag)
+- `wip` - Create/edit a work-in-progress prompt
+- `ready` - Move wip task to pending
+- `run [name]` - Launch pending task(s) in tmux windows
+- `watch` - Continuously poll and launch pending tasks
+- `attach [name]` - Switch to running task's tmux window (fuzzy select if no name)
+- `kill [name]` - Kill running task's tmux window, move to failed
+- `retry [name]` - Move failed/done task back to pending
+- `clean` - Remove all done/failed task files
+- `dir` - Print queue directory path
+
+Config: `~/.config/hiiro/queue/{wip,pending,running,done,failed}/`
+
+Key internals:
+- `Queue::Prompt` - Parses frontmatter to resolve task/tree/session for working directory
+- 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
+
+### Hiiro::ServiceManager (lib/hiiro/service_manager.rb)
+
+Manages background development services with tmux integration, env file management, and service groups.
+
+Subcommands (`h service <subcmd>`):
+- `ls`/`list` - List all services with running status, port, and base_dir
+- `start <name> [--use VAR=variation ...]` - Start a service or group; prepares env file first
+- `stop <name>` - Stop a running service (sends C-c to tmux pane or runs stop command)
+- `attach <name>` - Switch to service's tmux pane
+- `open <name>` - Open service URL in browser
+- `url <name>` / `port <name>` - Print service URL or port
+- `status <name>` - Show detailed service info (pid, pane, task, started_at)
+- `add` - Add new service via editor template
+- `rm`/`remove <name>` - Remove a service
+- `config` - Edit services.yml
+- `groups` - List all service groups and their members
+- `env <name>` - Show env_vars, their variation options, and base_env/env_file config
+
+Service config (`~/.config/hiiro/services.yml`):
+```yaml
+my-rails:
+  base_dir: apps/myapp
+  host: localhost
+  port: 3000
+  init: ["bundle install"]
+  start: bundle exec rails s -p 3000
+  stop: ""
+  cleanup: []
+  env_file: .env.development          # destination in base_dir
+  base_env: my-rails.env              # template in ~/.config/hiiro/env_templates/
+  env_vars:
+    GRAPHQL_URL:
+      variations:
+        local: http://localhost:4000/graphql
+        staging: https://graphql.staging.example.com/graphql
+```
+
+Service group config (same file, distinguished by `services:` key):
+```yaml
+my-stack:
+  services:
+    - name: my-rails
+      use:
+        GRAPHQL_URL: staging
+    - name: my-graphql
+```
+
+Key internals:
+- `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
+- State tracked in `~/.config/hiiro/services/running.yml`
+
+### Hiiro::RunnerTool (lib/hiiro/runner_tool.rb)
+
+Run dev tools (linters, formatters, test suites) against changed files.
+
+Subcommands (`h run [change_set] [tool_type] [file_group]`):
+- Default (no subcmd) - Run matching tools with positional filters
+- `ls` - List configured tools with type, group, extensions, and variations
+- `add` - Add new tool via editor template
+- `rm <name>` - Remove a tool
+- `config` - Edit tools.yml
+
+Arguments (positional, any order):
+- **change_set**: `dirty` (default, git status), `branch` (diff from main), `all`
+- **tool_type**: `lint`, `test`, `format`
+- **file_type_group**: custom group identifier (e.g., `ruby`, `frontend`)
+- `--variation`/`-v <name>` - Use a named tool variation
+
+Config (`~/.config/hiiro/tools.yml`):
+```yaml
+rubocop:
+  tool_type: lint
+  command: "rubocop [FILENAMES]"
+  file_type_group: ruby
+  file_extensions: "rb"
+  variations:
+    quick: "rubocop --only Style [FILENAMES]"
+    fix: "rubocop -A [FILENAMES]"
+```
+
+`[FILENAMES]` is replaced with the space-joined list of matching files.
+
+### Hiiro::AppFiles (lib/hiiro/app_files.rb)
+
+Track frequently-used files per application, open them together in your editor.
+
+Subcommands (`h file <subcmd>`):
+- `ls [app_name]` - List tracked files (all apps or specific app)
+- `add <app> <file1> [file2 ...]` - Add files to an app's file list
+- `rm <app> <file1> [file2 ...]` - Remove files
+- `edit <app>` - Open all tracked files in editor (vim uses `-O` for vertical splits)
+
+Config: `~/.config/hiiro/app_files.yml`
+
+Files are resolved relative to the current task's tree root when an environment is available.
+
+### Jumplist (bin/h-jumplist)
+
+Vim-style navigation history for tmux. Records pane/window/session changes and lets you jump backward/forward through your navigation history.
+
+Subcommands (`h jumplist <subcmd>`):
+- `setup` - Install tmux hooks and keybindings (`Ctrl-B` back, `Ctrl-F` forward)
+- `record` - Record current position (called automatically by tmux hooks)
+- `back` - Navigate to previous position
+- `forward` - Navigate to next position
+- `ls`/`list` - Show history with timestamps and current position marker
+- `clear` - Clear history
+- `path` - Print jumplist file path
+
+Config: `~/.config/hiiro/jumplist/` (per-client entries and position files, max 50 entries)
+
+Dead panes are automatically pruned. Duplicate consecutive entries are deduplicated. Forward history is truncated when navigating to a new location (like vim).
+
+### Using `run_child`
+
+`run_child` is the instance-level equivalent of `Hiiro.run` — it creates a child Hiiro instance scoped to a subcommand and immediately dispatches it. Use it instead of `make_child(...).run`:
+
+```ruby
+# Inside a subcommand handler or plugin:
+hiiro.add_subcmd(:service) do |*args|
+  sm = ServiceManager.new
+  hiiro.run_child(:service) do |h|
+    h.add_subcmd(:list) { sm.list }
+    h.add_subcmd(:start) { |name| sm.start(name) }
+  end
+end
+```
+
+This is equivalent to `hiiro.make_child(:service) { ... }.run`, but cleaner and mirrors the `Hiiro.run` / `Hiiro.init` relationship.
+
+## Coding Rules and Conventions
+
+### `Hiiro.run` vs `h = Hiiro.init` then `h.run`
+
+If the code sets up new classes to be used within the Hiiro set of subcommands
+or options/flags, inside the bin that calls them, then use the `init` version.
+
+Structure it like this:
+
+```ruby
+h = Hiiro.init(*ARGV) do
+  # ...
+end
+
+# setup classes here
+
+h.run
+```
+If the bin uses classes that are already defined, then use `Hiiro.run`
+
+### Keep docs current
+
+ALWAYS update `README.md` and any files in `docs/` or other markdown files that describe how to use hiiro, its bins, or how it works whenever you change behavior. Never let these go stale.
+
+## Key Files
+
+- `exe/h` - Entry point that loads lib/hiiro.rb
+- `exe/t`, `exe/tt` - Task CLI launchers over `Hiiro::TaskCli` (`lib/hiiro/task_cli.rb`)
+- `bin/h-*` - External subcommands (tmux wrappers, git helpers, jumplist, etc.)
+- `lib/hiiro.rb` - Main Hiiro class and Runners
+- `lib/hiiro/*.rb` - Supporting classes (Git, Matcher, Fuzzyfind, Todo, Shell, Options, Notification, Tmux, Queue, ServiceManager, RunnerTool, AppFiles)
+
+### not used anymore
+- `plugins/*.rb` - Reusable plugin modules (Pins, Project, Tasks, Notify)
+
+## External Dependencies
+
+- Ruby with `pry` gem
+- `tmux` for session/window/pane management
+- `sk` (skim) or `fzf` for fuzzy finding
+- `gh` CLI for GitHub operations (h-pr)
+- `terminal-notifier` for macOS notifications (notify plugin)
+- `claude` CLI for queue task execution
+
+## Configuration Locations
+
+All config lives in `~/.config/hiiro/`:
+- `plugins/` - Auto-loaded plugin files
+- `pins/` - Per-command YAML key-value storage
+- `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
+- `apps.yml` - App directory mappings for task plugin
+- `services.yml` - Service and service group definitions
+- `tools.yml` - Runner tool definitions
+- `app_files.yml` - Per-app tracked file lists
+
+
+# Groups of files
+
+## tmux-related files
+
+- bin/h-buffer
+- bin/h-pane
+- bin/h-window
+- bin/h-session
+- lib/hiiro/tmux.rb
+- lib/hiiro/tmux/*
+

data/CHANGELOG.md

@@ -1,6 +1,14 @@
 # Changelog
 
-## [Unreleased]
+## [0.1.377] - 2026-09-17
+
+### Changed
+- `h save` redesigned with slug-based filenames (`<timestamp>-<slug>.txt` / `<timestamp>-image.png`), image handling via `pngpaste`, and environment-configurable destination via `HIIRO_SAVED_DIR`
+
+### Added
+- `h save` subcommands: `ls`/`list`, `dir`, `show`/`cat`, `copy`, `open`, `edit`, `rm`/`remove` for managing saved files
+- `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
 
 ## [0.1.376] - 2026-09-14