ruborg 0.6.2 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 310a71ee8419f02ac2bee2fc03438a9d7b85e838e911202d99bb933bd21564d1
-  data.tar.gz: c7785d3fa514d20c901bd53b0923d0ccc044fa4fbf69b616009ba1ef16be9451
+  metadata.gz: c0db1cc300f1c33ec3ab6e1ad027b27fe379672e6344140fec4c5009f638de02
+  data.tar.gz: 29ffeb1331a718a2babd8febb11d12eca46db3f581074db8c66971d8737b21e4
 SHA512:
-  metadata.gz: 3532053d345494458c7c4eeee5c79808e73748d95360d71cac880d3db29a14205a4028c8d83aecff4a3fce3db217cf090403053be6fd860609d306271ee9c687
-  data.tar.gz: 0a22d49b96fb91c79eb3d5ee264f524f8712ca40c61523be12b0186e9a604c0e77e1d8f9507f970edefa21802c0bd74176e6db89c8d75c8234caef25fad0a57a
+  metadata.gz: 19ba4e200dd88d1f5251d0bf257b1591284c8a196571eb1f039cd6cf9bbca186774509f0adf72dadc2fc2da297589230bc0910b1a1466d6c016d5a0f2d39a6fe
+  data.tar.gz: 7af17006b577b9b48854b40214862d70c146197602ed94c83f1e5a4ec52b7b8f9273e09c827eebabd2c15a6c49974932d288c273bf4602c96240d2d7eba0ae8b

data/CHANGELOG.md

@@ -7,6 +7,54 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.7.0] - 2025-10-08
+
+### Added
+- **List Files in Archives**: New `--archive` option for list command to view files within a specific archive
+  - `ruborg list --repository documents --archive archive-name`
+  - Lists all files and directories contained in the specified archive
+  - Useful for finding specific files before restore operations
+- **File Metadata Retrieval**: New `metadata` command to retrieve detailed file information from archives
+  - `ruborg metadata ARCHIVE --repository documents --file /path/to/file`
+  - Auto-detects per-file archives and retrieves metadata without --file option
+  - Displays file size (human-readable), modification time, permissions, owner, group, and type
+  - Supports both standard and per-file archive modes
+- **Version Command**: New `ruborg version` command to display current ruborg version
+- **Enhanced Archive Naming**: Per-file archives now include actual filename in archive name
+  - Changed from `repo-hash-timestamp` to `repo-filename-hash-timestamp`
+  - Makes archive names human-readable and easier to identify
+  - Automatic filename sanitization (alphanumeric, dash, underscore, dot only)
+- **Smart Filename Truncation**: Archive names limited to 255 characters (filesystem limit)
+  - Intelligent truncation preserves file extensions when possible
+  - Handles very long filenames and repository names gracefully
+  - Example: `very-long-name...truncated.sql` becomes `very-lon.sql` with hash and timestamp
+- **File Modification Time in Archives**: Per-file mode uses file mtime instead of backup time
+  - Archive timestamps reflect when files were last modified, not when backup ran
+  - More accurate for tracking file changes over time
+  - Enables better retention based on actual file activity
+
+### Changed
+- **Separated Console Output from Logs**: Console now shows progress, logs show results
+  - Console displays repository headers, progress indicators, and completion messages
+  - Logs contain structured operational data with timestamps
+  - Repository name appears in both console headers and log entries (format: `[repo_name]`)
+  - Cleaner separation between user feedback and audit trails
+- **Enhanced Logging**: More detailed logging for backup operations
+  - Standard mode: Logs archive name with source count
+  - Per-file mode: Logs each file with its archive name
+  - Repository name prefix in all log entries for multi-repo clarity
+
+### Security
+- **Archive Name Validation**: Enhanced sanitization for archive names containing filenames
+  - Whitelist approach allows only safe characters: `[a-zA-Z0-9._-]`
+  - Replaces unsafe characters with underscores
+  - Prevents injection attacks via malicious filenames
+  - Archive names still passed as array elements to prevent shell injection
+- **Path Normalization**: Improved file path handling in metadata retrieval
+  - Correctly handles borg's path format (strips leading slash)
+  - Safe matching within JSON data from borg
+  - No path traversal vulnerabilities introduced
+
 ## [0.6.2] - 2025-10-08
 
 ### Fixed

data/README.md

@@ -25,7 +25,7 @@ A friendly Ruby frontend for [Borg Backup](https://www.borgbackup.org/). Ruborg
 - 📈 **Summary View** - Quick overview of all repositories and their configurations
 - 🔧 **Custom Borg Path** - Support for custom Borg executable paths per repository
 - 🏠 **Hostname Validation** - NEW! Restrict backups to specific hosts (global or per-repository)
-- ✅ **Well-tested** - Comprehensive test suite with RSpec (220 examples, 0 failures)
+- ✅ **Well-tested** - Comprehensive test suite with RSpec (220+ examples)
 - 🔒 **Security-focused** - Path validation, safe YAML loading, command injection protection
 
 ## Prerequisites
@@ -401,8 +401,11 @@ Current value: "true" (String). Set 'allow_remove_source: true' in configuration
 ### List Archives
 
 ```bash
-# List archives for a specific repository
+# List all archives for a specific repository
 ruborg list --repository documents
+
+# List files within a specific archive
+ruborg list --repository documents --archive archive-name
 ```
 
 ### Restore from Archive
@@ -434,6 +437,40 @@ The `info` command without `--repository` displays a summary showing:
 - Retention policies (global and per-repository overrides)
 - Number of sources per repository
 
+### Get File Metadata from Archives
+
+```bash
+# Get metadata from per-file archive (auto-detects single file)
+ruborg metadata archive-name --repository documents
+
+# Get metadata for specific file in standard archive
+ruborg metadata archive-name --repository documents --file /path/to/file.txt
+```
+
+The `metadata` command displays detailed file information:
+- File path
+- Size (human-readable format)
+- Modification time
+- File permissions (mode)
+- Owner and group
+- File type
+
+**Example output:**
+```
+═══════════════════════════════════════════════════════════════
+  FILE METADATA
+═══════════════════════════════════════════════════════════════
+
+Archive: databases-backup.sql-8b4c26d05aae-2025-10-08_19-05-07
+File: var/backups/database.sql
+Size: 45.67 MB
+Modified: 2025-10-08T19:05:07.123456
+Mode: -rw-r--r--
+User: postgres
+Group: postgres
+Type: regular file
+```
+
 ### Check Repository Compatibility
 
 ```bash
@@ -468,6 +505,13 @@ Borg version: 1.2.8
     Please upgrade Borg or migrate the repository
 ```
 
+### Show Version
+
+```bash
+# Display ruborg version
+ruborg version
+```
+
 ## Passbolt Integration
 
 Ruborg can retrieve encryption passphrases from Passbolt using the Passbolt CLI:
@@ -610,10 +654,12 @@ See [SECURITY.md](SECURITY.md) for detailed security information and best practi
 | `init REPOSITORY` | Initialize a new Borg repository | `--passphrase`, `--passbolt-id`, `--log` |
 | `validate` | Validate configuration file for type errors | `--config`, `--log` |
 | `backup` | Create a backup using config file | `--config`, `--repository`, `--all`, `--name`, `--remove-source`, `--log` |
-| `list` | List all archives in repository | `--config`, `--repository`, `--log` |
+| `list` | List archives or files in repository | `--config`, `--repository`, `--archive`, `--log` |
 | `restore ARCHIVE` | Restore files from archive | `--config`, `--repository`, `--destination`, `--path`, `--log` |
+| `metadata ARCHIVE` | Get file metadata from archive | `--config`, `--repository`, `--file`, `--log` |
 | `info` | Show repository information | `--config`, `--repository`, `--log` |
 | `check` | Check repository integrity and compatibility | `--config`, `--repository`, `--all`, `--verify-data`, `--log` |
+| `version` | Show ruborg version | None |
 
 ### Options
 

data/SECURITY.md

@@ -229,6 +229,17 @@ We will respond within 48 hours and work with you to address the issue.
 
 ## Security Audit History
 
+- **v0.7.0** (2025-10-08): Archive naming and metadata features - security review passed
+  - **NEW FEATURE**: List files within archives (--archive option)
+  - **NEW FEATURE**: File metadata retrieval from archives
+  - **NEW FEATURE**: Enhanced archive naming with filenames in per-file mode
+  - **SECURITY REVIEW**: Comprehensive security analysis found no exploitable vulnerabilities
+  - Archive name sanitization uses whitelist approach `[a-zA-Z0-9._-]`
+  - Array-based command execution prevents shell injection
+  - Safe JSON parsing without deserialization risks
+  - Path normalization handles borg's format safely (strips leading slash for matching only)
+  - All new features maintain existing security controls
+
 - **v0.6.1** (2025-10-08): Enhanced logging with sensitive data protection
   - **NEW FEATURE**: Comprehensive logging for backup operations, restoration, and deletion
   - Passwords and passphrases are NEVER logged (neither CLI nor Passbolt passwords)

data/lib/ruborg/backup.rb

@@ -25,10 +25,21 @@ module Ruborg
 
     def create_standard_archive(name, remove_source)
       archive_name = name || Time.now.strftime("%Y-%m-%d_%H-%M-%S")
+
+      # Show repository header in console only
+      print_repository_header
+
+      # Show progress in console
+      puts "Creating archive: #{archive_name}"
+
       cmd = build_create_command(archive_name)
 
       execute_borg_command(cmd)
 
+      # Log successful action
+      @logger&.info("[#{@repo_name}] Created archive #{archive_name} with #{@config.backup_paths.size} source(s)")
+      puts "✓ Archive created successfully"
+
       remove_source_files if remove_source
     end
 
@@ -38,24 +49,36 @@ module Ruborg
 
       raise BorgError, "No files found to backup" if files_to_backup.empty?
 
-      @logger&.info("Per-file mode: Found #{files_to_backup.size} file(s) to backup")
+      # Show repository header in console only
+      print_repository_header
 
-      timestamp = Time.now.strftime("%Y-%m-%d_%H-%M-%S")
+      puts "Found #{files_to_backup.size} file(s) to backup"
 
       files_to_backup.each_with_index do |file_path, index|
-        # Generate hash-based archive name
+        # Generate hash-based archive name with filename
         path_hash = generate_path_hash(file_path)
-        archive_name = name_prefix || "#{@repo_name}-#{path_hash}-#{timestamp}"
+        filename = File.basename(file_path)
+        sanitized_filename = sanitize_filename(filename)
+
+        # Use file modification time for timestamp (not backup creation time)
+        file_mtime = File.mtime(file_path).strftime("%Y-%m-%d_%H-%M-%S")
+
+        # Ensure archive name doesn't exceed 255 characters (filesystem limit)
+        archive_name = name_prefix || build_archive_name(@repo_name, sanitized_filename, path_hash, file_mtime)
 
-        @logger&.info("Backing up file #{index + 1}/#{files_to_backup.size}: #{file_path}")
+        # Show progress in console
+        puts "  [#{index + 1}/#{files_to_backup.size}] Backing up: #{file_path}"
 
         # Create archive for single file with original path as comment
         cmd = build_per_file_create_command(archive_name, file_path)
 
         execute_borg_command(cmd)
+
+        # Log successful action with details
+        @logger&.info("[#{@repo_name}] Archived #{file_path} in archive #{archive_name}")
       end
 
-      @logger&.info("Per-file backup completed: #{files_to_backup.size} file(s) backed up")
+      puts "✓ Per-file backup completed: #{files_to_backup.size} file(s) backed up"
 
       # NOTE: remove_source handled per file after successful backup
       remove_source_files if remove_source
@@ -97,6 +120,64 @@ module Ruborg
       Digest::SHA256.hexdigest(file_path)[0...12]
     end
 
+    def sanitize_filename(filename)
+      # Remove or replace characters that are not safe for archive names
+      # Allow alphanumeric, dash, underscore, and dot
+      sanitized = filename.gsub(/[^a-zA-Z0-9._-]/, "_")
+
+      # Ensure the sanitized name is not empty
+      sanitized = "file" if sanitized.empty? || sanitized.strip.empty?
+
+      sanitized
+    end
+
+    def build_archive_name(repo_name, sanitized_filename, path_hash, timestamp)
+      # Maximum filename length for most filesystems (ext4, NTFS, APFS)
+      max_length = 255
+
+      # Calculate fixed portions: separators (3) + hash (12) + timestamp (19)
+      fixed_length = 3 + path_hash.length + timestamp.length
+      repo_name_length = repo_name ? repo_name.length : 0
+
+      # Calculate available space for filename
+      available_for_filename = max_length - fixed_length - repo_name_length
+
+      # Truncate filename if necessary, preserving file extension if possible
+      truncated_filename = if sanitized_filename.length > available_for_filename
+                             truncate_with_extension(sanitized_filename, available_for_filename)
+                           else
+                             sanitized_filename
+                           end
+
+      "#{repo_name}-#{truncated_filename}-#{path_hash}-#{timestamp}"
+    end
+
+    def truncate_with_extension(filename, max_length)
+      return "" if max_length <= 0
+      return filename if filename.length <= max_length
+
+      # Try to preserve extension (last .xxx)
+      if filename.include?(".") && filename !~ /^\./
+        parts = filename.rpartition(".")
+        basename = parts[0]
+        extension = parts[2]
+
+        # Reserve space for extension plus dot
+        extension_length = extension.length + 1
+
+        if extension_length < max_length
+          basename_max = max_length - extension_length
+          "#{basename[0...basename_max]}.#{extension}"
+        else
+          # Extension too long, just truncate entire filename
+          filename[0...max_length]
+        end
+      else
+        # No extension, just truncate
+        filename[0...max_length]
+      end
+    end
+
     def build_per_file_create_command(archive_name, file_path)
       cmd = [@repository.borg_path, "create"]
       cmd += ["--compression", @config.compression]
@@ -250,5 +331,11 @@ module Ruborg
         File.expand_path(path)
       end
     end
+
+    def print_repository_header
+      puts "\n" + ("=" * 60)
+      puts "  Repository: #{@repo_name}"
+      puts "=" * 60
+    end
   end
 end

data/lib/ruborg/cli.rb

@@ -60,9 +60,9 @@ module Ruborg
       raise
     end
 
-    desc "list", "List all archives in the repository"
+    desc "list", "List all archives in the repository or files in a specific archive"
+    option :archive, type: :string, desc: "Archive name to list files from"
     def list
-      @logger.info("Listing archives in repository")
       config = Config.new(options[:config])
 
       raise ConfigError, "Please specify --repository" unless options[:repository]
@@ -77,7 +77,8 @@ module Ruborg
       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 = Repository.new(repo_config["path"], passphrase: passphrase, borg_options: borg_opts, borg_path: borg_path,
+                                                 logger: @logger)
 
       # Auto-initialize repository if configured
       # Use strict boolean checking: only true enables, everything else disables
@@ -89,10 +90,17 @@ module Ruborg
         puts "Repository auto-initialized at #{repo_config["path"]}"
       end
 
-      repo.list
-      @logger.info("Successfully listed archives")
+      if options[:archive]
+        @logger.info("Listing files in archive: #{options[:archive]}")
+        repo.list_archive(options[:archive])
+        @logger.info("Successfully listed files in archive")
+      else
+        @logger.info("Listing archives in repository")
+        repo.list
+        @logger.info("Successfully listed archives")
+      end
     rescue Error => e
-      @logger.error("Failed to list archives: #{e.message}")
+      @logger.error("Failed to list: #{e.message}")
       raise
     end
 
@@ -116,7 +124,8 @@ module Ruborg
       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 = Repository.new(repo_config["path"], passphrase: passphrase, borg_options: borg_opts, borg_path: borg_path,
+                                                 logger: @logger)
 
       # Create backup config wrapper for compatibility
       backup_config = BackupConfig.new(repo_config, merged_config)
@@ -155,7 +164,8 @@ module Ruborg
       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 = Repository.new(repo_config["path"], passphrase: passphrase, borg_options: borg_opts, borg_path: borg_path,
+                                                 logger: @logger)
 
       # Auto-initialize repository if configured
       # Use strict boolean checking: only true enables, everything else disables
@@ -234,7 +244,8 @@ module Ruborg
 
         if errors.any?
           puts "Configuration has errors that must be fixed.\n\n"
-          raise ConfigError, "Configuration validation failed"
+          @logger.error("Configuration validation failed")
+          exit 1
         else
           puts "Configuration is valid but has warnings.\n\n"
         end
@@ -246,76 +257,57 @@ module Ruborg
       raise
     end
 
-    desc "validate", "Validate configuration file for errors and type issues"
-    def validate_config
-      @logger.info("Validating configuration file: #{options[:config]}")
+    desc "version", "Show ruborg version"
+    def version
+      require_relative "version"
+      puts "ruborg #{Ruborg::VERSION}"
+      @logger.info("Version checked: #{Ruborg::VERSION}")
+    end
+
+    desc "metadata ARCHIVE", "Get file metadata from an archive"
+    option :file, type: :string, desc: "Specific file path (required for standard archives, auto for per-file)"
+    def metadata(archive_name)
+      @logger.info("Getting metadata for archive: #{archive_name}")
       config = Config.new(options[:config])
 
-      puts "\n═══════════════════════════════════════════════════════════════"
-      puts "  CONFIGURATION VALIDATION"
-      puts "═══════════════════════════════════════════════════════════════\n\n"
+      raise ConfigError, "Please specify --repository" unless options[:repository]
 
-      errors = []
-      warnings = []
+      repo_config = config.get_repository(options[:repository])
+      raise ConfigError, "Repository '#{options[:repository]}' not found" unless repo_config
 
-      # Validate global boolean settings
       global_settings = config.global_settings
-      errors.concat(validate_boolean_setting(global_settings, "auto_init", "global"))
-      errors.concat(validate_boolean_setting(global_settings, "auto_prune", "global"))
-      errors.concat(validate_boolean_setting(global_settings, "allow_remove_source", "global"))
+      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"]
 
-      # Validate borg_options booleans
-      if global_settings["borg_options"]
-        warnings.concat(validate_borg_option(global_settings["borg_options"], "allow_relocated_repo", "global"))
-        warnings.concat(validate_borg_option(global_settings["borg_options"], "allow_unencrypted_repo", "global"))
-      end
+      repo = Repository.new(repo_config["path"], passphrase: passphrase, borg_options: borg_opts, borg_path: borg_path,
+                                                 logger: @logger)
 
-      # Validate per-repository settings
-      config.repositories.each do |repo|
-        repo_name = repo["name"]
-        errors.concat(validate_boolean_setting(repo, "auto_init", repo_name))
-        errors.concat(validate_boolean_setting(repo, "auto_prune", repo_name))
-        errors.concat(validate_boolean_setting(repo, "allow_remove_source", repo_name))
+      raise BorgError, "Repository does not exist at #{repo_config["path"]}" unless repo.exists?
 
-        if repo["borg_options"]
-          warnings.concat(validate_borg_option(repo["borg_options"], "allow_relocated_repo", repo_name))
-          warnings.concat(validate_borg_option(repo["borg_options"], "allow_unencrypted_repo", repo_name))
-        end
-      end
+      # Get file metadata
+      metadata = repo.get_file_metadata(archive_name, file_path: options[:file])
 
-      # Display results
-      if errors.empty? && warnings.empty?
-        puts "✓ Configuration is valid"
-        puts "  No type errors or warnings found\n\n"
-      else
-        unless errors.empty?
-          puts "❌ ERRORS FOUND (#{errors.size}):"
-          errors.each do |error|
-            puts "  - #{error}"
-          end
-          puts ""
-        end
-
-        unless warnings.empty?
-          puts "⚠️  WARNINGS (#{warnings.size}):"
-          warnings.each do |warning|
-            puts "  - #{warning}"
-          end
-          puts ""
-        end
-
-        if errors.any?
-          puts "Configuration has errors that must be fixed.\n\n"
-          exit 1
-        else
-          puts "Configuration is valid but has warnings.\n\n"
-        end
-      end
+      # Display metadata
+      puts "\n═══════════════════════════════════════════════════════════════"
+      puts "  FILE METADATA"
+      puts "═══════════════════════════════════════════════════════════════\n\n"
+      puts "Archive: #{archive_name}"
+      puts "File: #{metadata["path"]}"
+      puts "Size: #{format_size(metadata["size"])}"
+      puts "Modified: #{metadata["mtime"]}"
+      puts "Mode: #{metadata["mode"]}"
+      puts "User: #{metadata["user"]}"
+      puts "Group: #{metadata["group"]}"
+      puts "Type: #{metadata["type"]}"
+      puts ""
 
-      @logger.info("Configuration validation completed")
+      @logger.info("Successfully retrieved metadata for #{metadata["path"]}")
     rescue Error => e
-      @logger.error("Validation failed: #{e.message}")
-      error_exit(e)
+      @logger.error("Failed to get metadata: #{e.message}")
+      raise
     end
 
     desc "check", "Check repository integrity and compatibility"
@@ -363,7 +355,8 @@ module Ruborg
       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 = Repository.new(repo_config["path"], passphrase: passphrase, borg_options: borg_opts, borg_path: borg_path,
+                                                 logger: @logger)
 
       unless repo.exists?
         puts "  ✗ Repository does not exist at #{repo_config["path"]}"
@@ -480,6 +473,21 @@ module Ruborg
       parts.empty? ? "none" : parts.join(", ")
     end
 
+    def format_size(bytes)
+      return "0 B" if bytes.nil? || bytes.zero?
+
+      units = %w[B KB MB GB TB]
+      size = bytes.to_f
+      unit_index = 0
+
+      while size >= 1024 && unit_index < units.length - 1
+        size /= 1024.0
+        unit_index += 1
+      end
+
+      format("%.2f %s", size, units[unit_index])
+    end
+
     def get_passphrase(passphrase, passbolt_id)
       return passphrase if passphrase
       return Passbolt.new(resource_id: passbolt_id, logger: @logger).get_password if passbolt_id
@@ -543,7 +551,8 @@ module Ruborg
       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 = Repository.new(repo_config["path"], passphrase: passphrase, borg_options: borg_opts, borg_path: borg_path,
+                                                 logger: @logger)
 
       # Auto-initialize if configured
       # Use strict boolean checking: only true enables, everything else disables
@@ -571,7 +580,8 @@ module Ruborg
 
       # 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)
+      backup = Backup.new(repo, config: backup_config, retention_mode: retention_mode, repo_name: repo_name,
+                                logger: @logger)
 
       archive_name = options[:name] ? sanitize_archive_name(options[:name]) : nil
       @logger.info("Creating archive#{"s" if retention_mode == "per_file"}: #{archive_name || "auto-generated"}")

data/lib/ruborg/repository.rb

@@ -41,6 +41,95 @@ module Ruborg
       execute_borg_command(cmd)
     end
 
+    def list_archive(archive_name)
+      raise BorgError, "Repository does not exist at #{@path}" unless exists?
+      raise BorgError, "Archive name cannot be empty" if archive_name.nil? || archive_name.strip.empty?
+
+      cmd = [@borg_path, "list", "#{@path}::#{archive_name}"]
+      execute_borg_command(cmd)
+    end
+
+    def get_archive_info(archive_name)
+      raise BorgError, "Repository does not exist at #{@path}" unless exists?
+      raise BorgError, "Archive name cannot be empty" if archive_name.nil? || archive_name.strip.empty?
+
+      require "json"
+      require "open3"
+
+      cmd = [@borg_path, "info", "#{@path}::#{archive_name}", "--json"]
+      env = build_borg_env
+
+      stdout, stderr, status = Open3.capture3(env, *cmd)
+      raise BorgError, "Failed to get archive info: #{stderr}" unless status.success?
+
+      JSON.parse(stdout)
+    rescue JSON::ParserError => e
+      raise BorgError, "Failed to parse archive info: #{e.message}"
+    end
+
+    def get_file_metadata(archive_name, file_path: nil)
+      raise BorgError, "Repository does not exist at #{@path}" unless exists?
+      raise BorgError, "Archive name cannot be empty" if archive_name.nil? || archive_name.strip.empty?
+
+      require "json"
+      require "open3"
+
+      # Get archive info to check if it's a per-file archive
+      archive_info = get_archive_info(archive_name)
+      comment = archive_info.dig("archives", 0, "comment")
+
+      # If it's a per-file archive (has comment with original path), get metadata for that file
+      # Otherwise, require file_path parameter
+      if comment && !comment.empty?
+        # Per-file archive - get metadata for the single file
+        get_file_metadata_from_archive(archive_name, nil)
+      else
+        # Standard archive - require file_path
+        raise BorgError, "file_path parameter required for standard archives" if file_path.nil? || file_path.empty?
+
+        get_file_metadata_from_archive(archive_name, file_path)
+      end
+    end
+
+    private
+
+    def get_file_metadata_from_archive(archive_name, file_path)
+      require "json"
+      require "open3"
+
+      cmd = [@borg_path, "list", "#{@path}::#{archive_name}", "--json-lines"]
+      env = build_borg_env
+
+      stdout, stderr, status = Open3.capture3(env, *cmd)
+      raise BorgError, "Failed to list archive contents: #{stderr}" unless status.success?
+
+      # Parse JSON lines
+      files = stdout.lines.map do |line|
+        JSON.parse(line)
+      end
+
+      # If file_path specified, find that specific file
+      if file_path
+        # Borg stores absolute paths by stripping the leading slash
+        # For example: /var/folders/foo -> var/folders/foo
+        # Try both the original path and the path with leading slash removed
+        normalized_path = file_path.start_with?("/") ? file_path[1..] : file_path
+        file_metadata = files.find { |f| f["path"] == file_path || f["path"] == normalized_path }
+        raise BorgError, "File '#{file_path}' not found in archive" unless file_metadata
+
+        file_metadata
+      else
+        # Per-file archive - return metadata for the single file (first file)
+        raise BorgError, "Archive appears to be empty" if files.empty?
+
+        files.first
+      end
+    rescue JSON::ParserError => e
+      raise BorgError, "Failed to parse file metadata: #{e.message}"
+    end
+
+    public
+
     def prune(retention_policy = {}, retention_mode: "standard")
       raise BorgError, "Repository does not exist at #{@path}" unless exists?
       raise BorgError, "No retention policy specified" if retention_policy.nil? || retention_policy.empty?

data/lib/ruborg/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Ruborg
-  VERSION = "0.6.2"
+  VERSION = "0.7.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ruborg
 version: !ruby/object:Gem::Version
-  version: 0.6.2
+  version: 0.7.0
 platform: ruby
 authors:
 - Michail Pantelelis
@@ -149,7 +149,6 @@ files:
 - lib/ruborg/passbolt.rb
 - lib/ruborg/repository.rb
 - lib/ruborg/version.rb
-- ruborg.gemspec
 - ruborg.yml.example
 homepage: https://github.com/mpantel/ruborg
 licenses:

data/ruborg.gemspec

@@ -1,46 +0,0 @@
-# frozen_string_literal: true
-
-require_relative "lib/ruborg/version"
-
-Gem::Specification.new do |spec|
-  spec.name = "ruborg"
-  spec.version = Ruborg::VERSION
-  spec.authors = ["Michail Pantelelis"]
-  spec.email = ["mpantel@aegean.gr"]
-
-  spec.summary = "A friendly Ruby frontend for Borg backup"
-  spec.description = "Ruborg provides a user-friendly interface to Borg backup. " \
-                     "It reads YAML configuration files and orchestrates backup operations, " \
-                     "supporting repository creation, backup management, and Passbolt integration."
-  spec.homepage = "https://github.com/mpantel/ruborg"
-  spec.license = "MIT"
-  spec.required_ruby_version = ">= 3.2.0"
-
-  spec.metadata["homepage_uri"] = spec.homepage
-  spec.metadata["source_code_uri"] = "#{spec.homepage}.git"
-  spec.metadata["changelog_uri"] = "#{spec.homepage}/blob/main/CHANGELOG.md"
-  spec.metadata["rubygems_mfa_required"] = "true"
-
-  # Specify which files should be added to the gem when it is released.
-  spec.files = Dir.chdir(__dir__) do
-    `git ls-files -z`.split("\x0").reject do |f|
-      (File.expand_path(f) == __FILE__) ||
-        f.start_with?(*%w[bin/ test/ spec/ features/ .git .github appveyor Gemfile])
-    end
-  end
-  spec.bindir = "exe"
-  spec.executables = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
-  spec.require_paths = ["lib"]
-
-  # Dependencies
-  spec.add_dependency "psych", "~> 5.0"
-  spec.add_dependency "thor", "~> 1.3"
-
-  # Development dependencies
-  spec.add_development_dependency "bundler", "~> 2.0"
-  spec.add_development_dependency "bundler-audit", "~> 0.9"
-  spec.add_development_dependency "rake", "~> 13.0"
-  spec.add_development_dependency "rspec", "~> 3.0"
-  spec.add_development_dependency "rubocop", "~> 1.0"
-  spec.add_development_dependency "rubocop-rspec", "~> 3.0"
-end