ruborg 0.9.0 → 0.9.4

data/lib/ruborg/catalog.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Ruborg
+  # Read-only view over the ArchiveCache for searching and reporting.
+  # Never writes back to the cache.
+  class Catalog
+    def initialize(repo_path)
+      @cache = ArchiveCache.new(repo_path).fetch
+    end
+
+    # Returns all cached entries sorted by file path.
+    def list
+      @cache.entries.sort_by { |e| e[:path].to_s }
+    end
+
+    # Returns entries whose :path matches +pattern+ (a Regexp or regex string).
+    # Raises CatalogError on invalid regex.
+    def search(pattern)
+      regex = pattern.is_a?(Regexp) ? pattern : Regexp.new(pattern)
+      list.select { |e| regex.match?(e[:path].to_s) }
+    rescue RegexpError => e
+      raise CatalogError, "Invalid regex pattern: #{e.message}"
+    end
+
+    # Returns a summary hash with aggregate statistics.
+    def stats
+      all = list
+      {
+        total_archives: all.size,
+        unique_paths: all.map { |e| e[:path] }.uniq.size,
+        total_size: all.sum { |e| e[:size].to_i },
+        source_dirs: all.map { |e| e[:source_dir] }.uniq.reject(&:empty?).size
+      }
+    end
+  end
+end

data/lib/ruborg/cli.rb

@@ -1,10 +1,12 @@
 # frozen_string_literal: true
 
 require "thor"
+require "json"
 
 module Ruborg
   # Command-line interface for ruborg
   class CLI < Thor
+    DEFAULT_LOCK_WAIT = 300
     class_option :config, type: :string, default: "ruborg.yml", desc: "Path to configuration file"
     class_option :log, type: :string, desc: "Path to log file"
     class_option :repository, type: :string, aliases: "-r", desc: "Repository name (for multi-repo configs)"
@@ -74,11 +76,7 @@ module Ruborg
       merged_config = global_settings.merge(repo_config)
       validate_hostname(merged_config)
       passphrase = fetch_passphrase_for_repo(merged_config)
-      borg_opts = merged_config["borg_options"] || {}
-      borg_path = merged_config["borg_path"]
-
-      repo = Repository.new(repo_config["path"], passphrase: passphrase, borg_options: borg_opts, borg_path: borg_path,
-                                                 logger: @logger)
+      repo = build_repo(repo_config["path"], merged_config, passphrase)
 
       # Auto-initialize repository if configured
       # Use strict boolean checking: only true enables, everything else disables
@@ -121,11 +119,7 @@ module Ruborg
       merged_config = global_settings.merge(repo_config)
       validate_hostname(merged_config)
       passphrase = fetch_passphrase_for_repo(merged_config)
-      borg_opts = merged_config["borg_options"] || {}
-      borg_path = merged_config["borg_path"]
-
-      repo = Repository.new(repo_config["path"], passphrase: passphrase, borg_options: borg_opts, borg_path: borg_path,
-                                                 logger: @logger)
+      repo = build_repo(repo_config["path"], merged_config, passphrase)
 
       # Create backup config wrapper for compatibility
       backup_config = BackupConfig.new(repo_config, merged_config)
@@ -161,11 +155,7 @@ module Ruborg
       global_settings = config.global_settings
       merged_config = global_settings.merge(repo_config)
       passphrase = fetch_passphrase_for_repo(merged_config)
-      borg_opts = merged_config["borg_options"] || {}
-      borg_path = merged_config["borg_path"]
-
-      repo = Repository.new(repo_config["path"], passphrase: passphrase, borg_options: borg_opts, borg_path: borg_path,
-                                                 logger: @logger)
+      repo = build_repo(repo_config["path"], merged_config, passphrase)
 
       # Auto-initialize repository if configured
       # Use strict boolean checking: only true enables, everything else disables
@@ -311,11 +301,7 @@ module Ruborg
       merged_config = global_settings.merge(repo_config)
       validate_hostname(merged_config)
       passphrase = fetch_passphrase_for_repo(merged_config)
-      borg_opts = merged_config["borg_options"] || {}
-      borg_path = merged_config["borg_path"]
-
-      repo = Repository.new(repo_config["path"], passphrase: passphrase, borg_options: borg_opts, borg_path: borg_path,
-                                                 logger: @logger)
+      repo = build_repo(repo_config["path"], merged_config, passphrase)
 
       unless repo.exists?
         puts "  ✗ Repository does not exist at #{repo_config["path"]}"
@@ -358,6 +344,95 @@ module Ruborg
 
     public
 
+    desc "catalog", "Search or browse the local archive metadata catalog (no borg calls)"
+    option :search, type: :string, desc: "Regex pattern to filter by file path"
+    option :stats, type: :boolean, default: false, desc: "Show catalog statistics instead of listing entries"
+    option :json, type: :boolean, default: false, desc: "Output as JSON"
+    def catalog
+      config = Config.new(options[:config])
+
+      raise ConfigError, "Please specify --repository" unless options[:repository]
+
+      repo_config = config.get_repository(options[:repository])
+      raise ConfigError, "Repository '#{options[:repository]}' not found" unless repo_config
+
+      global_settings = config.global_settings
+      merged_config = global_settings.merge(repo_config)
+      cat = Catalog.new(repo_config["path"])
+
+      if options[:stats]
+        print_catalog_stats(cat.stats, options[:json])
+      elsif options[:search]
+        results = cat.search(options[:search])
+        print_catalog_entries(results, options[:json])
+      else
+        print_catalog_entries(cat.list, options[:json])
+      end
+
+      @logger.info("Catalog query on repository '#{merged_config["name"]}'")
+    rescue Error => e
+      @logger.error("Catalog failed: #{e.message}")
+      raise
+    end
+
+    desc "lock", "Check for and optionally break a Borg repository lock"
+    option :break, type: :boolean, default: false,
+                   desc: "Break the lock via borg break-lock (requires --yes)"
+    option :force, type: :boolean, default: false,
+                   desc: "Force-remove lock files directly without invoking borg (requires --yes)"
+    option :yes,   type: :boolean, default: false, desc: "Confirm the destructive operation"
+    def lock
+      config = Config.new(options[:config])
+
+      raise ConfigError, "Please specify --repository" unless options[:repository]
+      raise ConfigError, "Use --break or --force, not both" if options[:break] && options[:force]
+
+      repo_config = config.get_repository(options[:repository])
+      raise ConfigError, "Repository '#{options[:repository]}' not found" unless repo_config
+
+      global_settings = config.global_settings
+      merged_config = global_settings.merge(repo_config)
+      passphrase = fetch_passphrase_for_repo(merged_config)
+      repo = build_repo(repo_config["path"], merged_config, passphrase)
+
+      repo_locked   = repo.locked?
+      cache_locked  = repo.cache_locked?
+
+      unless repo_locked || cache_locked
+        puts "No lock found for repository '#{repo_config["name"]}'"
+        @logger.info("Lock check: no lock found for '#{repo_config["name"]}'")
+        return
+      end
+
+      warn "Lock detected on repository '#{repo_config["name"]}' (#{repo_config["path"]}):"
+      warn "  Repository lock : #{repo_locked  ? "LOCKED" : "clear"}"
+      warn "  Cache lock      : #{cache_locked ? "LOCKED" : "clear"}"
+      @logger.warn("Lock detected on '#{repo_config["name"]}' — repo=#{repo_locked}, cache=#{cache_locked}")
+
+      unless options[:break] || options[:force]
+        warn "  Run with --break --yes (via borg) or --force --yes (direct removal)."
+        exit 1
+      end
+
+      unless options[:yes]
+        warn "  Add --yes to confirm."
+        exit 1
+      end
+
+      if options[:force]
+        removed = repo.force_break_lock
+        puts "Force-removed lock files for '#{repo_config["name"]}': #{removed.join(", ")}"
+        @logger.info("Force-removed lock files for '#{repo_config["name"]}'")
+      else
+        repo.break_lock
+        puts "Lock broken for repository '#{repo_config["name"]}'"
+        @logger.info("Lock broken for repository '#{repo_config["name"]}'")
+      end
+    rescue Error => e
+      @logger.error("Lock command failed: #{e.message}")
+      raise
+    end
+
     desc "version", "Show ruborg and borg versions"
     def version
       require_relative "version"
@@ -408,11 +483,7 @@ module Ruborg
       merged_config = global_settings.merge(repo_config)
       validate_hostname(merged_config)
       passphrase = fetch_passphrase_for_repo(merged_config)
-      borg_opts = merged_config["borg_options"] || {}
-      borg_path = merged_config["borg_path"]
-
-      repo = Repository.new(repo_config["path"], passphrase: passphrase, borg_options: borg_opts, borg_path: borg_path,
-                                                 logger: @logger)
+      repo = build_repo(repo_config["path"], merged_config, passphrase)
 
       raise BorgError, "Repository does not exist at #{repo_config["path"]}" unless repo.exists?
 
@@ -441,6 +512,49 @@ module Ruborg
 
     private
 
+    def print_catalog_entries(entries, as_json)
+      if as_json
+        puts JSON.generate(entries.map { |e| stringify_entry(e) })
+        return
+      end
+
+      if entries.empty?
+        puts "No entries found."
+        return
+      end
+
+      puts "\n#{"FILE PATH".ljust(55)}  #{"SIZE".ljust(10)}  ARCHIVE"
+      puts "-" * 90
+      entries.each do |e|
+        puts "#{truncate(e[:path].to_s, 55).ljust(55)}  #{format_size(e[:size].to_i).ljust(10)}  #{e[:archive_name]}"
+      end
+      puts "\n#{entries.size} entry/entries."
+    end
+
+    def print_catalog_stats(stats, as_json)
+      if as_json
+        puts JSON.generate(stats)
+        return
+      end
+
+      puts "\n═══════════════════════════════════════════════════════════════"
+      puts "  CATALOG STATISTICS"
+      puts "═══════════════════════════════════════════════════════════════\n\n"
+      puts "  Total archives : #{stats[:total_archives]}"
+      puts "  Unique files   : #{stats[:unique_paths]}"
+      puts "  Source dirs    : #{stats[:source_dirs]}"
+      puts "  Total size     : #{format_size(stats[:total_size])}"
+      puts ""
+    end
+
+    def stringify_entry(entry)
+      entry.transform_keys(&:to_s)
+    end
+
+    def truncate(str, max)
+      str.length > max ? "...#{str[-(max - 3)..]}" : str
+    end
+
     def show_repositories_summary(config)
       repositories = config.repositories
       global_settings = config.global_settings
@@ -529,7 +643,7 @@ module Ruborg
         unit_index += 1
       end
 
-      format("%.2f %s", size, units[unit_index])
+      "#{format("%.2f", size)} #{units[unit_index]}"
     end
 
     def get_passphrase(passphrase, passbolt_id)
@@ -588,30 +702,32 @@ module Ruborg
       puts "\n--- Backing up repository: #{repo_name} ---"
       @logger.info("Backing up repository: #{repo_name}")
 
-      # Merge global settings with repo-specific settings (repo-specific takes precedence)
       merged_config = global_settings.merge(repo_config)
       validate_hostname(merged_config)
 
+      retention_mode = merged_config["retention_mode"] || "standard"
+      auto_prune = merged_config["auto_prune"] == true
+      retention_policy = merged_config["retention"]
+      will_prune = auto_prune && retention_policy && !retention_policy.empty?
+      stage_total = will_prune ? 3 : 2
+
+      progress = Progress.new
+      progress.stage(1, stage_total, "Verifying repository: #{repo_name}")
+      progress.spin("Preparing...")
+
       passphrase = fetch_passphrase_for_repo(merged_config)
-      borg_opts = merged_config["borg_options"] || {}
-      borg_path = merged_config["borg_path"]
-      repo = Repository.new(repo_config["path"], passphrase: passphrase, borg_options: borg_opts, borg_path: borg_path,
-                                                 logger: @logger)
+      lock_wait = (merged_config["lock_wait"] || DEFAULT_LOCK_WAIT).to_i
+      repo = build_repo(repo_config["path"], merged_config, passphrase)
 
-      # Auto-initialize if configured
-      # Use strict boolean checking: only true enables, everything else disables
-      auto_init = merged_config["auto_init"]
-      auto_init = false unless auto_init == true
+      auto_init = merged_config["auto_init"] == true
       if auto_init && !repo.exists?
         @logger.info("Auto-initializing repository at #{repo_config["path"]}")
         repo.create
         puts "Repository auto-initialized at #{repo_config["path"]}"
       end
 
-      # Get retention mode (defaults to standard)
-      retention_mode = merged_config["retention_mode"] || "standard"
+      wait_for_lock_clear(repo, repo_name, lock_wait, progress)
 
-      # Validate remove_source permission with strict type checking
       if options[:remove_source]
         allow_remove_source = merged_config["allow_remove_source"]
         unless allow_remove_source.is_a?(TrueClass)
@@ -622,14 +738,14 @@ module Ruborg
         end
       end
 
-      # Get skip_hash_check setting (defaults to false)
-      skip_hash_check = merged_config["skip_hash_check"]
-      skip_hash_check = false unless skip_hash_check == true
+      skip_hash_check = merged_config["skip_hash_check"] == true
+
+      backup_label = retention_mode == "per_file" ? "Backing up files (per-file mode)" : "Creating archive"
+      progress.stage(2, stage_total, backup_label)
 
-      # Create backup config wrapper
       backup_config = BackupConfig.new(repo_config, merged_config)
       backup = Backup.new(repo, config: backup_config, retention_mode: retention_mode, repo_name: repo_name,
-                                logger: @logger, skip_hash_check: skip_hash_check)
+                                logger: @logger, skip_hash_check: skip_hash_check, progress: progress)
 
       archive_name = options[:name] ? sanitize_archive_name(options[:name]) : nil
       @logger.info("Creating archive#{"s" if retention_mode == "per_file"}: #{archive_name || "auto-generated"}")
@@ -640,27 +756,55 @@ module Ruborg
       backup.create(name: archive_name, remove_source: options[:remove_source])
       @logger.info("Backup created successfully")
 
-      if retention_mode == "per_file"
-        puts "✓ Per-file backups created"
-      else
-        puts "✓ Backup created: #{archive_name || "auto-generated"}"
-      end
       puts "  Sources removed" if options[:remove_source]
 
-      # Auto-prune if configured and retention policy exists
-      # Use strict boolean checking: only true enables, everything else disables
-      auto_prune = merged_config["auto_prune"]
-      auto_prune = false unless auto_prune == true
-      retention_policy = merged_config["retention"]
-
-      return unless auto_prune && retention_policy && !retention_policy.empty?
+      return unless will_prune
 
       mode_desc = retention_mode == "per_file" ? "per-file mode" : "standard mode"
+      progress.stage(3, stage_total, "Pruning old archives (#{mode_desc})")
+      progress.spin("Pruning...")
       @logger.info("Auto-pruning repository: #{repo_name} (#{mode_desc})")
-      puts "  Pruning old backups (#{mode_desc})..."
       repo.prune(retention_policy, retention_mode: retention_mode)
       @logger.info("Pruning completed successfully for #{repo_name}")
-      puts "  ✓ Pruning completed"
+      progress.done("Pruning completed")
+    end
+
+    def wait_for_lock_clear(repo, repo_name, lock_wait, progress)
+      return unless repo.locked?
+
+      @logger.warn("Repository '#{repo_name}' is locked — waiting up to #{lock_wait}s")
+      elapsed = 0
+      interval = 5
+
+      progress.spin("Repository locked — waiting for lock to clear (0s / #{lock_wait}s)…")
+
+      while repo.locked? && elapsed < lock_wait
+        sleep interval
+        elapsed += interval
+        progress.spin("Repository locked — waiting for lock to clear (#{elapsed}s / #{lock_wait}s)…")
+      end
+
+      progress.stop_spin
+
+      if repo.locked?
+        raise BorgError,
+              "Repository '#{repo_name}' is still locked after #{lock_wait}s. " \
+              "Run 'ruborg lock --repository #{repo_name}' to inspect, or " \
+              "'ruborg lock --repository #{repo_name} --break --yes' to clear."
+      end
+
+      @logger.info("Lock cleared for '#{repo_name}' after #{elapsed}s")
+    end
+
+    def build_repo(repo_path, merged_config, passphrase)
+      Repository.new(
+        repo_path,
+        passphrase: passphrase,
+        borg_options: merged_config["borg_options"] || {},
+        borg_path: merged_config["borg_path"],
+        lock_wait: merged_config["lock_wait"]&.to_i,
+        logger: @logger
+      )
     end
 
     def fetch_passphrase_for_repo(repo_config)

data/lib/ruborg/config.rb

@@ -41,7 +41,7 @@ module Ruborg
 
     def global_settings
       @data.slice("passbolt", "compression", "encryption", "auto_init", "borg_options", "log_file", "retention",
-                  "auto_prune", "hostname", "allow_remove_source", "borg_path", "skip_hash_check")
+                  "auto_prune", "hostname", "allow_remove_source", "borg_path", "skip_hash_check", "lock_wait")
     end
 
     private
@@ -54,12 +54,12 @@ module Ruborg
     # Valid configuration keys at each level
     VALID_GLOBAL_KEYS = %w[
       hostname compression encryption auto_init auto_prune allow_remove_source
-      log_file borg_path passbolt borg_options retention repositories skip_hash_check
+      log_file borg_path passbolt borg_options retention repositories skip_hash_check lock_wait
     ].freeze
 
     VALID_REPOSITORY_KEYS = %w[
       name description path hostname retention_mode passbolt retention sources
-      compression encryption auto_init auto_prune borg_options allow_remove_source skip_hash_check
+      compression encryption auto_init auto_prune borg_options allow_remove_source skip_hash_check lock_wait
     ].freeze
 
     VALID_SOURCE_KEYS = %w[name paths exclude].freeze

data/lib/ruborg/progress.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+module Ruborg
+  # Terminal progress display: named stages, inline progress bar, and spinner.
+  # Writes to $stderr so stdout remains clean for --json or piped output.
+  # Degrades to plain text lines when output is not a TTY (piped / redirected).
+  class Progress
+    SPINNER_FRAMES = %w[⠋ ⠙ ⠹ ⠸ ⠼ ⠴ ⠦ ⠧ ⠇ ⠏].freeze
+    BAR_WIDTH = 28
+    LINE_WIDTH = 80
+
+    def initialize(output: $stderr)
+      @output = output
+      @tty = output.respond_to?(:isatty) && output.isatty
+      @spinner_thread = nil
+      @spin_label = nil
+      @spin_start = nil
+    end
+
+    # Print a numbered stage header: "[2/3] Label"
+    def stage(index, total, label)
+      stop_spin
+      clear_line if @tty
+      @output.puts "[#{index}/#{total}] #{label}"
+    end
+
+    # Start a spinner on the current line for an indeterminate operation.
+    # Appends elapsed time after 3 seconds so long-running steps are visible.
+    # Call stop_spin (or done) to halt it.
+    def spin(label)
+      stop_spin
+      return unless @tty
+
+      @spin_label = label
+      @spin_start = Time.now
+      frame = 0
+      @spinner_thread = Thread.new do
+        loop do
+          elapsed = (Time.now - @spin_start).to_i
+          time_str = elapsed >= 3 ? " (#{elapsed}s)" : ""
+          @output.print "\r  #{SPINNER_FRAMES[frame % SPINNER_FRAMES.size]}  #{@spin_label}#{time_str}"
+          frame += 1
+          sleep 0.1
+        end
+      end
+    end
+
+    # Update the label on a running spinner without restarting it.
+    # Safe to call from the main thread while the spinner runs in the background.
+    def update_spin(label)
+      @spin_label = label
+    end
+
+    # Stop the spinner and erase its line.
+    def stop_spin
+      return unless @spinner_thread
+
+      @spinner_thread.kill
+      @spinner_thread.join(0.2)
+      @spinner_thread = nil
+      clear_line if @tty
+    end
+
+    # Redraw an inline progress bar. Call once per item in a loop.
+    # label is truncated to fit the terminal line.
+    def bar(current, total, label = "")
+      return unless @tty
+
+      pct = total.positive? ? (current.to_f / total) : 0
+      filled = (BAR_WIDTH * pct).round
+      bar_str = filled.positive? ? "#{"=" * (filled - 1)}>" : ""
+      bar_str = bar_str.ljust(BAR_WIDTH)
+      short_label = truncate_left(label.to_s, 28)
+      @output.print "\r  [#{bar_str}]  #{current}/#{total}  #{short_label.ljust(28)}"
+    end
+
+    # Halt any in-progress display and print a completion line.
+    def done(label = nil)
+      stop_spin
+      clear_line if @tty
+      @output.puts "  ✓ #{label}" if label
+    end
+
+    private
+
+    def clear_line
+      @output.print "\r#{" " * LINE_WIDTH}\r"
+    end
+
+    def truncate_left(str, max)
+      str.length > max ? "...#{str[-(max - 3)..]}" : str
+    end
+  end
+end