hiiro 0.1.307 → 0.1.308.pre.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e00081cfbdc892d4c4e799cbeeb927b6d70139ad18e0b5d6abca846fe3fb1a99
-  data.tar.gz: 57a103e3413c9370cb3de8968d73aa451fa36f4bcea6ea2d5d1834a56c3fd7c1
+  metadata.gz: 5133c5b05e6f2040b092c49a8ff75a1e665f9506d5a6b7afc9078dcd9c3d20a2
+  data.tar.gz: bea25caa37de50a810b76b72b8eebe5eb1fd37141542aaea21da1932e3dbae9d
 SHA512:
-  metadata.gz: c832c6372c95f54e41e0f4932ac404d85495adb1724838e8b5aed601567b5519a7b9c82e1e60ce095ca8d02963e855d631c8b99ae42cdb785007ea275f5e8635
-  data.tar.gz: f062a27380003af64dedaf9c4a950744073c255221de17a84b4d01b2879c2bd9697811799e997803c0b347232aab5928b7eaabf1b7c5449e0cd0a52b2deadef1
+  metadata.gz: 321291e9a574a533d3647c7c4a54040fdbf993c174923958a4d1fdb7936bee373c838c689ca10fb50b48940d4a9aefc662c4a72714442271c7180eccf82d748f
+  data.tar.gz: 15d46bd5f44affa4fb6418f6f76e61cef848a4ade2a975cba450825aeb730da8362fbc0a885241bad31bae4969f752063de95d9143ab72127576850cf3c4e804

data/CHANGELOG.md

@@ -1 +1,123 @@
-Done. CHANGELOG.md has been updated with v0.1.307 entry at the top, documenting the two recent commits.
+```markdown
+# Changelog
+
+## [0.1.308.pre.1] - 2026-03-31
+
+### Added
+- `Hiiro::Effects` injectable interface for testable file system and command execution
+- `null_fs` to `TestHarness` for testing without side effects
+- Effects helpers and accessors to `TestHarness` for controlled effect simulation
+- `Hiiro::Invocation` and `Hiiro::InvocationResolution` tracking in PaneHome SQLite migration
+
+### Changed
+- Refactor effects layer: expose `executor` and `fs` as accessors on `Hiiro::Effects`
+- `h-db` command now includes h-pane in SQLite migration
+- Gem version handling: treat non-main branches as pre-release in publish script
+
+### Fixed
+- `h-branch co` and `h-branch rm` restore extra argument pass-through
+- Test suite: add missing `TestHarness` stubs and fix pre-existing test failures
+- Test fixtures: anchor `load_bin` path to project root instead of `Dir.pwd`
+
+### Deprecated
+- `SystemCallCapture` — use `Hiiro::Effects` helpers in `TestHarness` instead
+
+## [Unreleased]
+
+### Added
+- `Hiiro::DB` — SQLite foundation via Sequel; `DB.setup!` creates all tables, `DB.connection` establishes connection eagerly at load time; supports `HIIRO_TEST_DB=sqlite::memory:` for tests
+- `lib/hiiro/db.rb` — one-time YAML→SQLite migration (`migrate_yaml!`) guarded by `schema_migrations` table; dual-write mode (`dual_write?` / `disable_dual_write!`) for gradual cutover
+- `lib/hiiro/branch.rb` — `Hiiro::Branch` Sequel model for worktree branch records
+- `lib/hiiro/tracked_pr.rb` — `Hiiro::TrackedPr` Sequel model for tracked PR records (`:prs` table)
+- `lib/hiiro/link.rb` — `Hiiro::Link` Sequel model with `matches?`, `display_string`, `to_h` helpers
+- `lib/hiiro/project.rb` — `Hiiro::Project` Sequel model
+- `lib/hiiro/pane_home.rb` — `Hiiro::PaneHome` Sequel model with `data_json` JSON blob
+- `lib/hiiro/pin_record.rb` — `Hiiro::PinRecord` Sequel model for per-command key-value pin storage
+- `lib/hiiro/task_record.rb` — `Hiiro::TaskRecord` Sequel model for task metadata
+- `lib/hiiro/app_record.rb` — `Hiiro::AppRecord` Sequel model for app directory mappings
+- `lib/hiiro/assignment.rb` — `Hiiro::Assignment` Sequel model for worktree→branch assignments
+- `lib/hiiro/reminder.rb` — `Hiiro::Reminder` Sequel model
+- `lib/hiiro/invocation.rb` — `Hiiro::Invocation` and `Hiiro::InvocationResolution` Sequel models; every CLI invocation is recorded to SQLite for history/analytics
+- `bin/h-db` — new subcommand: `h db status`, `h db tables`, `h db q <sql>`, `h db migrate`, `h db restore`
+
+### Changed
+- `lib/hiiro/todo.rb` — `TodoItem` is now a `Sequel::Model`; `TodoManager` reads/writes via SQLite with YAML dual-write fallback
+- `lib/hiiro/tags.rb` — `Tag` is now a `Sequel::Model`; tag operations persist to SQLite with YAML dual-write fallback
+- `lib/hiiro/pinned_pr_manager.rb` — `PinnedPR` is now a `Sequel::Model` (`lib/hiiro/pinned_pr.rb`); `PinnedPRManager` reads/writes via SQLite with YAML dual-write
+- `lib/hiiro/projects.rb` — `Projects#from_config` reads from `Hiiro::Project` SQLite model with YAML fallback
+- `lib/hiiro/tasks.rb` — `TaskManager::Config` reads/writes tasks and apps via `Hiiro::TaskRecord` and `Hiiro::AppRecord` SQLite models
+- `bin/h-branch` — `BranchManager` reads/writes via `Hiiro::Branch` and `Hiiro::TrackedPr` SQLite models with YAML dual-write fallback; adds `q`/`query` subcommands for raw SQL inspection
+- `bin/h-link` — reads/writes links via `Hiiro::Link` SQLite model with YAML dual-write fallback; adds `q`/`query` subcommands
+- `bin/h-pane` — load/save pane homes via `Hiiro::PaneHome` model with YAML dual-write
+- `bin/h-pr` — adds `q`/`query` subcommands for inspecting PR records via raw SQL
+- `plugins/pins.rb` — `Pin` class reads/writes via `Hiiro::PinRecord` SQLite model with YAML dual-write fallback
+
+## [0.1.306] - 2026-03-30
+
+### Changed
+- Increase delayed_update sleep duration from 5s to 15s
+- Add logging for delayed_update invocation in publish script
+
+## [0.1.305] - 2026-03-30
+
+### Changed
+- Refactor: use delayed_update subcommand instead of direct update call
+- Improve gem version matching regex in version check
+
+## [0.1.304] - 2026-03-30
+
+### Changed
+- h-notify: use universal log instead of per-session logging
+- Todo output simplified
+
+## [0.1.302] - 2026-03-30
+
+### Fixed
+- Truncate output lines to terminal width in tasks plugin
+
+## [0.1.301]
+
+### Added
+- Check version delayed update functionality
+
+### Changed
+- h-claude: add verbose flags and refactor glob_path handling
+
+### Fixed
+- Use exact session matching to prevent tmux prefix ambiguity
+
+## [0.1.300]
+
+### Added
+- h-claude: fulltext search option for agents/commands/skills
+
+### Changed
+- Refactor h-claude directory traversal and file globbing
+
+## [0.1.299]
+
+### Added
+- h-pr open: support opening multiple PRs
+
+## [0.1.298]
+
+### Changed
+- Use Pathname to walk up directory tree
+- h-claude agents/commands/skills walk from pwd up to home
+
+## [0.1.297]
+
+### Added
+- h rnext subcommand
+
+## [0.1.296]
+
+### Changed
+- Refactor PR filter logic to pinned_pr_manager
+- Move PR filter logic to Pr#matches_filters?
+
+## [0.1.295]
+
+### Changed
+- Filter logic changes for PR management
+```

data/CLAUDE.md

@@ -221,6 +221,38 @@ 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:
@@ -246,6 +278,26 @@ 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:

data/bin/h-branch

@@ -25,23 +25,20 @@ class BranchManager
       puts "WARNING: Not in a task session, saving without task info"
     end
 
-    data = load_data
-    data['branches'] ||= []
-
-    existing = data['branches'].find do |b|
-      b['name'] == branch_name && b['task'] == entry[:task]
-    end
-
+    existing = Hiiro::Branch.find_by_name(branch_name)
     if existing
-      existing.merge!(entry.transform_keys(&:to_s))
-      existing['updated_at'] = Time.now.iso8601
       puts "Updated branch '#{branch_name}' for task '#{entry[:task]}'"
     else
-      data['branches'] << entry.transform_keys(&:to_s).merge('created_at' => Time.now.iso8601)
       puts "Saved branch '#{branch_name}' for task '#{entry[:task]}'"
     end
 
-    save_data(data)
+    save_branch(
+      name:     entry[:name],
+      worktree: entry[:worktree],
+      task:     entry[:task],
+      tmux:     entry[:tmux],
+      sha:      entry[:sha]
+    )
     show_entry(entry)
     true
   end
@@ -79,53 +76,58 @@ class BranchManager
   end
 
   def rename_saved(old_name, new_name)
-    data = load_data
-    changed = false
-    (data['branches'] || []).each do |b|
-      if b['name'] == old_name
-        b['name'] = new_name
-        b['updated_at'] = Time.now.iso8601
-        changed = true
-      end
-    end
-    save_data(data) if changed
-    changed
+    branch = Hiiro::Branch.find_by_name(old_name)
+    return false unless branch
+    branch.update(name: new_name, updated_at: Time.now.iso8601)
+    save_yaml_backup
+    true
   end
 
   def remove_saved(branch_name)
-    data = load_data
-    before = (data['branches'] || []).length
-    data['branches'] = (data['branches'] || []).reject { |b| b['name'] == branch_name }
-    save_data(data) if data['branches'].length < before
+    branch = Hiiro::Branch.find_by_name(branch_name)
+    return unless branch
+    branch.destroy
+    save_yaml_backup
   end
 
   def get_note(branch_name = nil)
     branch_name ||= current_branch
-    saved_entry(branch_name)&.[]('note')
+    Hiiro::Branch.find_by_name(branch_name)&.note
   end
 
   def set_note(text, branch_name = nil)
     branch_name ||= current_branch
-    data = load_data
-    data['branches'] ||= []
-    entry = data['branches'].find { |b| b['name'] == branch_name }
-    unless entry
-      new_entry = build_entry(branch_name).transform_keys(&:to_s).merge('created_at' => Time.now.iso8601)
-      data['branches'] << new_entry
-      entry = data['branches'].last
-    end
-    if text.nil?
-      entry.delete('note')
-    else
-      entry['note'] = text
-    end
-    entry['updated_at'] = Time.now.iso8601
-    save_data(data)
+    branch = Hiiro::Branch.find_by_name(branch_name)
+    unless branch
+      entry = build_entry(branch_name)
+      branch = Hiiro::Branch.create(
+        name:       branch_name,
+        worktree:   entry[:worktree],
+        task:       entry[:task],
+        tmux_json:  Hiiro::DB::JSON.dump(entry[:tmux]),
+        sha:        entry[:sha],
+        created_at: Time.now.iso8601
+      )
+    end
+    branch.update(note: text, updated_at: Time.now.iso8601)
+    save_yaml_backup
   end
 
   def load_data
-    return {} unless File.exist?(data_file)
-    YAML.safe_load_file(data_file) || {}
+    Hiiro::Branch.ordered.all.each_with_object({ 'branches' => [] }) do |b, data|
+      data['branches'] << {
+        'name'       => b.name,
+        'worktree'   => b.worktree,
+        'task'       => b.task,
+        'tmux'       => b.tmux.empty? ? nil : b.tmux,
+        'sha'        => b.sha,
+        'note'       => b.note,
+        'created_at' => b.created_at
+      }.compact
+    end
+  rescue => e
+    warn "Branch DB read failed: #{e}"
+    load_yaml_fallback
   end
 
   def build_entry(branch_name)
@@ -134,11 +136,11 @@ class BranchManager
     sha = `git rev-parse HEAD 2>/dev/null`.strip
 
     {
-      name: branch_name,
-      sha: sha.empty? ? nil : sha,
+      name:     branch_name,
+      sha:      sha.empty? ? nil : sha,
       worktree: current_task&.tree_name,
-      task: current_task&.name,
-      tmux: tmux_info
+      task:     current_task&.name,
+      tmux:     tmux_info
     }
   end
 
@@ -153,8 +155,8 @@ class BranchManager
 
     {
       'session' => `tmux display-message -p '#S'`.strip,
-      'window' => `tmux display-message -p '#W'`.strip,
-      'pane' => ENV['TMUX_PANE']
+      'window'  => `tmux display-message -p '#W'`.strip,
+      'pane'    => ENV['TMUX_PANE']
     }
   end
 
@@ -170,13 +172,46 @@ class BranchManager
     end
   end
 
-  def data_file
-    File.join(Dir.home, '.config', 'hiiro', 'branches.yml')
+  def save_branch(name:, worktree:, task:, tmux: nil, sha: nil)
+    existing = Hiiro::Branch.find_by_name(name)
+    if existing
+      existing.update(
+        worktree:   worktree,
+        task:       task,
+        tmux_json:  Hiiro::DB::JSON.dump(tmux),
+        sha:        sha,
+        updated_at: Time.now.iso8601
+      )
+    else
+      Hiiro::Branch.create(
+        name:       name,
+        worktree:   worktree,
+        task:       task,
+        tmux_json:  Hiiro::DB::JSON.dump(tmux),
+        sha:        sha,
+        created_at: Time.now.iso8601
+      )
+    end
+    save_yaml_backup
   end
 
-  def save_data(data)
+  def save_yaml_backup
+    data = load_data
     FileUtils.mkdir_p(File.dirname(data_file))
     File.write(data_file, YAML.dump(data))
+  rescue => e
+    warn "Branch YAML backup failed: #{e}"
+  end
+
+  def load_yaml_fallback
+    return {} unless File.exist?(data_file)
+    YAML.safe_load_file(data_file) || {}
+  rescue
+    {}
+  end
+
+  def data_file
+    File.join(Dir.home, '.config', 'hiiro', 'branches.yml')
   end
 end
 
@@ -492,7 +527,7 @@ Hiiro.run(*ARGV) do
       branch = selected.strip
     end
 
-    system('git', 'checkout', branch)
+    system('git', 'checkout', branch, *opts.args[1..])
   end
 
   add_subcmd(:rm, :remove) do |*rm_args|
@@ -510,7 +545,7 @@ Hiiro.run(*ARGV) do
       branch = selected.strip
     end
 
-    system('git', 'branch', '-d', branch)
+    system('git', 'branch', '-d', branch, *opts.args[1..])
   end
 
   add_subcmd(:rename) do |new_name = nil, old_name = nil|
@@ -913,6 +948,48 @@ Hiiro.run(*ARGV) do
     system('git', 'log', '--oneline', '--decorate', "#{forkpoint}..HEAD")
   }
 
+  add_subcmd(:q, :query) { |*args|
+    def branch_query(args)
+      opts = Hiiro::Options.parse(args) { flag(:all, short: :a, desc: 'show all rows (no limit)') }
+      query_args = opts.args
+      db = Hiiro::DB.connection
+      limit = opts.all ? nil : 50
+
+      if query_args.empty?
+        ds = db[:branches]
+        ds = ds.limit(limit) if limit
+        rows = ds.all
+      elsif query_args[0].include?(' ') || query_args[0].upcase =~ /\A(SELECT|INSERT|UPDATE|DELETE|WITH)/
+        sql = query_args.join(' ')
+        rows = db.fetch(sql).all
+        rows = rows.first(limit) if limit
+      else
+        conditions = query_args.each_with_object({}) do |pair, h|
+          k, v = pair.split('=', 2)
+          h[k] = v if k && v
+        end
+        ds = db[:branches]
+        conditions.each { |k, v| ds = ds.where(k.to_sym => v) }
+        ds = ds.limit(limit) if limit
+        rows = ds.all
+      end
+
+      return puts "(no results)" if rows.empty?
+      keys = rows.first.keys
+      col_widths = keys.map { |k| [k.to_s.length, rows.map { |r| r[k].to_s.length }.max].max.clamp(0, 60) }
+      header = keys.each_with_index.map { |k, i| k.to_s.ljust(col_widths[i]) }.join("  ")
+      puts header
+      puts "-" * header.length
+      rows.each do |row|
+        puts keys.each_with_index.map { |k, i|
+          val = row[k].to_s; val = val[0..57] + "..." if val.length > 60; val.ljust(col_widths[i])
+        }.join("  ")
+      end
+      puts "(#{rows.length} rows)"
+    end
+    branch_query(args)
+  }
+
   add_subcmd(:forkpoint) { |upstream = nil, branch = nil|
     branch ||= 'HEAD'
     upstream ||= %w[origin/master master origin/main main].find { |ref|

data/bin/h-db

@@ -0,0 +1,178 @@
+#!/usr/bin/env ruby
+
+require 'hiiro'
+require 'pathname'
+
+def print_table(rows)
+  return puts "(no results)" if rows.empty?
+
+  keys = rows.first.keys
+  col_widths = keys.map { |k|
+    [k.to_s.length, rows.map { |r| r[k].to_s.length }.max].max.clamp(0, 60)
+  }
+
+  header = keys.each_with_index.map { |k, i| k.to_s.ljust(col_widths[i]) }.join("  ")
+  puts header
+  puts "-" * header.length
+  rows.each do |row|
+    puts keys.each_with_index.map { |k, i|
+      val = row[k].to_s
+      val = val[0..57] + "..." if val.length > 60
+      val.ljust(col_widths[i])
+    }.join("  ")
+  end
+  puts "(#{rows.length} rows)"
+end
+
+def run_query(args)
+  opts = Hiiro::Options.parse(args) { flag(:all, short: :a, desc: 'show all rows (no limit)') }
+  query_args = opts.args
+
+  db = Hiiro::DB.connection
+  limit = opts.all ? nil : 50
+
+  if query_args.empty?
+    puts "Usage: h db q <table> [key=value ...] OR h db q \"SQL\""
+    return
+  elsif query_args[0].include?(' ') || query_args[0].upcase =~ /\A(SELECT|INSERT|UPDATE|DELETE|WITH)/
+    sql = query_args.join(' ')
+    rows = db.fetch(sql).all
+    rows = rows.first(limit) if limit
+    print_table(rows)
+  else
+    table = query_args[0]
+    conditions = query_args[1..].each_with_object({}) do |pair, h|
+      k, v = pair.split('=', 2)
+      h[k] = v if k && v
+    end
+    ds = db[table.to_sym]
+    conditions.each { |k, v| ds = ds.where(k.to_sym => v) }
+    ds = ds.limit(limit) if limit
+    rows = ds.all
+    print_table(rows)
+  end
+end
+
+Hiiro.run(*ARGV) do
+  add_subcmd(:status) do
+    db_path = Hiiro::DB::DB_FILE
+    db_size = File.exist?(db_path) ? File.size(db_path) : 0
+    db_size_str = if db_size >= 1_048_576
+      "#{(db_size / 1_048_576.0).round(1)} MB"
+    elsif db_size >= 1024
+      "#{(db_size / 1024.0).round(1)} KB"
+    else
+      "#{db_size} B"
+    end
+
+    puts "DB: #{db_path} (#{db_size_str})"
+
+    migrated = Hiiro::DB.migrated?
+    if migrated
+      ran_at = begin
+        Hiiro::DB.connection[:schema_migrations].where(name: 'yaml_import').first&.[](:ran_at)
+      rescue
+        nil
+      end
+      puts "Migration: complete#{ran_at ? " (#{ran_at})" : ""}"
+    else
+      puts "Migration: not run"
+    end
+
+    puts "Dual-write: #{Hiiro::DB.dual_write? ? 'active' : 'disabled'}"
+    puts
+
+    db = Hiiro::DB.connection
+    tables = db.tables - [:schema_migrations]
+    if tables.any?
+      puts "Table counts:"
+      max_len = tables.map(&:to_s).map(&:length).max
+      tables.sort.each do |t|
+        count = db[t].count rescue '?'
+        puts "  #{t.to_s.ljust(max_len)}  #{count.to_s.rjust(6)}"
+      end
+    end
+
+    config_dir = File.expand_path('~/.config/hiiro')
+    archives = Dir.glob(File.join(config_dir, 'sqlite-migration.*.tar.gz')).sort
+    puts
+    if archives.empty?
+      puts "Backups: (none)"
+    else
+      puts "Backups:"
+      archives.each { |a| puts "  #{a}" }
+    end
+  end
+
+  add_subcmd(:tables) do
+    Hiiro::DB.connection.tables.sort.each { |t| puts t }
+  end
+
+  add_subcmd(:q) { |*args| run_query(args) }
+  add_subcmd(:query) { |*args| run_query(args) }
+
+  add_subcmd(:migrate) do
+    unless Hiiro::DB.migrated?
+      puts "Migration has not run yet. Run `h db status` for details."
+      next
+    end
+
+    unless Hiiro::DB.dual_write?
+      puts "Already fully migrated. Dual-write is already disabled."
+      next
+    end
+
+    print "This will archive and remove all YAML files. Continue? [y/N] "
+    response = $stdin.gets.chomp
+    unless response.downcase == 'y'
+      puts "Aborted."
+      next
+    end
+
+    config_dir = File.expand_path('~/.config/hiiro')
+    timestamp  = Time.now.strftime('%Y%m%d%H%M%S')
+    archive    = File.join(config_dir, "sqlite-migration.#{timestamp}.tar.gz")
+
+    yml_files = Dir.glob(File.join(config_dir, '**/*.yml'))
+                   .reject { |f| f.end_with?('.yml.bak') }
+                   .map { |f| Pathname.new(f).relative_path_from(config_dir).to_s }
+
+    if yml_files.empty?
+      puts "No YAML files found to back up."
+    else
+      puts "Creating backup: #{archive}"
+      Dir.chdir(config_dir) do
+        system('tar', 'cvzf', archive, *yml_files)
+      end
+      puts "\nRemoving YAML files..."
+      yml_files.each do |rel_path|
+        full_path = File.join(config_dir, rel_path)
+        puts "  rm #{full_path}"
+        File.delete(full_path)
+      end
+    end
+
+    Hiiro::DB.disable_dual_write!
+
+    puts
+    puts "Full migration complete."
+    puts "Backup saved: #{archive}"
+    puts
+    puts "To restore YAML files:"
+    puts "  cd #{config_dir}"
+    puts "  tar xvzf #{File.basename(archive)}"
+  end
+
+  add_subcmd(:restore) do
+    config_dir = File.expand_path('~/.config/hiiro')
+    archives   = Dir.glob(File.join(config_dir, 'sqlite-migration.*.tar.gz')).sort
+    if archives.empty?
+      puts "No backup archives found in #{config_dir}"
+      next
+    end
+    latest = archives.last
+    puts "Restoring from #{File.basename(latest)}..."
+    Dir.chdir(config_dir) { system('tar', 'xvzf', latest) }
+    puts "Done. YAML files restored."
+  end
+end