hiiro 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: a553e1c19ac099d93b9232da28a1953a83b7c2a379c8ddb05475a43aa58e31fb
+  data.tar.gz: 33d06064609e82b1d1da5e7ec83ecfcd90d49cac93cc6a7b8cd3930ab4e48a57
+SHA512:
+  metadata.gz: 4418cdbaa9056006099e9ec9e82eccc85c625ff380d4e92f93f1db6e4bc1b48a0b5617566c3c8d36c308b7db1c6f9caac4e9f596ac56663d5499be05bac1ce4b
+  data.tar.gz: bf153421fbf79ad299203ba871b9907521dd2674f554efb34619a90c84dfb4ab2b0c56c2d3b32cdab2820cd35efa94e5e5b0baa2d24dbf7619cd7181e98323bd

data/CLAUDE.md

@@ -0,0 +1,101 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## 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
+
+# Search plugin code
+h plugin rg "pattern"
+
+# Edit a specific plugin
+h plugin edit pins
+
+# Syntax check Ruby files
+ruby -c bin/h
+ruby -c plugins/*.rb
+```
+
+There is no build step or test suite. This is a pure Ruby CLI tool.
+
+## 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.init()` are available in subcommand handlers:
+
+```ruby
+hiiro = Hiiro.init(*ARGV, cwd: Dir.pwd)
+hiiro.add_subcmd(:pwd) do |*args, **values|
+  puts values[:cwd]
+end
+```
+
+## Key Files
+
+- `bin/h` - Core framework (~420 lines)
+- `bin/h-*` - External subcommands (tmux wrappers, video operations)
+- `plugins/*.rb` - Reusable plugin modules (Pins, Project, Task, Tmux, Notify)
+
+## External Dependencies
+
+- Ruby with `pry` gem
+- `tmux` for session/window/pane management
+- `ffmpeg`/`ffprobe` for video operations (h-video)
+- `terminal-notifier` for macOS notifications (notify plugin)
+
+## 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
+- `projects.yml` - Project directory aliases
+- `apps.yml` - App directory mappings for task plugin

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,276 @@
+# Hiiro
+
+A lightweight, extensible CLI framework for Ruby. Build your own multi-command tools similar to `git` or `docker`.
+
+## Features
+
+- **Subcommand dispatch** - Route commands to executables or Ruby blocks
+- **Abbreviation matching** - Type `h ex hel` instead of `h example hello`
+- **Plugin system** - Extend functionality with reusable modules
+- **Per-command storage** - Each command gets its own pin/config namespace
+
+See [docs/](docs/) for detailed documentation on all subcommands.
+
+## Installation
+
+```sh
+# Copy the main script
+cp bin/h ~/bin/h
+chmod +x ~/bin/h
+
+# Copy subcommands (optional)
+cp bin/h-* ~/bin/
+
+# Copy plugins (optional)
+mkdir -p ~/.config/hiiro/plugins
+cp plugins/*.rb ~/.config/hiiro/plugins/
+```
+
+Ensure `~/bin` is in your `$PATH`.
+
+### Dependencies
+
+```sh
+gem install pry
+# For notify plugin (macOS)
+brew install terminal-notifier
+```
+
+## Quick Start
+
+```sh
+# List available subcommands
+h
+
+# Edit the main h script
+h edit
+
+# Get paths
+h path      # Print current directory
+h ppath     # Print project root (git repo root + relative dir)
+h rpath     # Print relative directory from git root
+
+# Simple test
+h ping
+# => pong
+```
+
+## Adding Subcommands
+
+### Method 1: External Executables
+
+Create an executable named `h-<subcommand>` anywhere in your `$PATH`:
+
+```sh
+# ~/bin/h-greet
+#!/bin/bash
+echo "Hello, $1!"
+```
+
+```sh
+h greet World
+# => Hello, World!
+```
+
+For nested subcommands, use hiiro in your script:
+
+```ruby
+#!/usr/bin/env ruby
+# ~/bin/h-example
+
+load File.join(Dir.home, 'bin/h')
+
+Hiiro.init(*ARGV) do |hiiro|
+  hiiro.add_subcommand(:hello) { puts "Hi!" }
+  hiiro.add_subcommand(:bye)   { puts "Goodbye!" }
+end.run
+```
+
+```sh
+h example hello  # => Hi!
+h example bye    # => Goodbye!
+```
+
+### Method 2: Inline Subcommands
+
+Modify `bin/h` directly to add subcommands to the base `h` command:
+
+```ruby
+hiiro = Hiiro.init(*ARGV, plugins: [Pins, Project, Task], cwd: Dir.pwd)
+
+hiiro.add_subcommand(:hello) do |*args|
+  puts "Hello, #{args.first || 'World'}!"
+end
+
+hiiro.run
+```
+
+Global values (like `cwd`) are passed to all subcommand handlers via keyword arguments:
+
+```ruby
+hiiro.add_subcommand(:pwd) do |*args, **values|
+  puts values[:cwd]  # Access the cwd passed during init
+end
+```
+
+## Abbreviations
+
+Any subcommand can be abbreviated as long as the prefix uniquely matches:
+
+```sh
+h ex hel    # matches h example hello
+h te        # matches h test (if unique)
+h pp        # matches h ppath
+```
+
+If multiple commands match, the first match wins and a warning is logged (when logging is enabled).
+
+## Built-in Plugins
+
+### Pins
+
+Key-value storage persisted per command:
+
+```sh
+h pin                     # List all pins
+h pin mykey               # Get value
+h pin mykey myvalue       # Set value
+h pin set mykey myvalue   # Set value (explicit)
+h pin rm mykey            # Remove pin
+```
+
+Pins are stored in `~/.config/hiiro/pins/<command>.yml`.
+
+### Tmux Subcommands
+
+Hiiro includes several tmux wrapper commands for managing sessions, windows, panes, and buffers. See [docs/](docs/) for full documentation.
+
+```sh
+h session ls              # List tmux sessions
+h window new              # Create new window
+h pane split              # Split current pane
+h buffer ls               # List paste buffers
+```
+
+### Project
+
+Quick project navigation with tmux integration:
+
+```sh
+h project myproj          # cd to ~/proj/myproj and start tmux session
+```
+
+Projects can be configured in `~/.config/hiiro/projects.yml`:
+
+```yaml
+myproject: /path/to/project
+work: ~/work/main
+```
+
+### Task
+
+Manage development tasks across git worktrees in `~/work/`:
+
+```sh
+h task list               # Show trees and their active tasks
+h task start TICKET-123   # Start working on a task
+h task status             # Show current task info
+h task app frontend       # Open app directory in new tmux window
+h task save               # Save current tmux window state
+h task stop               # Release tree for other tasks
+```
+
+Configure apps in `~/.config/hiiro/apps.yml`:
+
+```yaml
+frontend: apps/frontend
+api: services/api
+admin: admin_portal/admin
+```
+
+### Notify (macOS)
+
+Desktop notifications via `terminal-notifier`:
+
+```sh
+h notify "Build complete"
+h notify "Click me" "https://example.com"
+```
+
+### Video
+
+FFmpeg wrapper for common video operations:
+
+```sh
+h video info movie.mp4        # Human-readable video summary
+h video resize720 movie.mp4   # Resize to 720p
+h video clip movie.mp4 00:01:30 60  # Extract 60s clip starting at 1:30
+h video gif movie.mp4         # Create animated GIF
+h video help                  # Full command list
+```
+
+See [docs/h-video.md](docs/h-video.md) for complete documentation.
+
+### Plugin
+
+Manage hiiro plugins:
+
+```sh
+h plugin ls                   # List installed plugins
+h plugin edit pins            # Edit a plugin file
+h plugin rg "some_method"     # Search plugin code
+```
+
+## Writing Plugins
+
+Plugins are Ruby modules that extend Hiiro instances:
+
+```ruby
+# ~/.config/hiiro/plugins/myplugin.rb
+
+module MyPlugin
+  def self.load(hiiro)
+    attach_methods(hiiro)
+    add_subcommands(hiiro)
+  end
+
+  def self.add_subcommands(hiiro)
+    hiiro.add_subcmd(:mycmd) do |*args|
+      # command logic
+    end
+  end
+
+  def self.attach_methods(hiiro)
+    hiiro.instance_eval do
+      def my_helper
+        # helper method available to other plugins
+      end
+    end
+  end
+end
+```
+
+Load plugins in your command:
+
+```ruby
+Hiiro.init(*ARGV, plugins: [MyPlugin]) do |hiiro|
+  # ...
+end
+```
+
+## Configuration
+
+All configuration lives in `~/.config/hiiro/`:
+
+```
+~/.config/hiiro/
+  plugins/        # Plugin files (auto-loaded)
+  pins/           # Pin storage (per command)
+  tasks/          # Task metadata
+  projects.yml    # Project aliases
+  apps.yml        # App directory mappings
+```
+
+## License
+
+MIT

data/Rakefile

@@ -0,0 +1,3 @@
+require "bundler/gem_tasks"
+
+task default: :build