appydave-tools 0.37.0 → 0.39.0

data/docs/code-quality/report-2025-01-21.md

@@ -0,0 +1,342 @@
+# Code Quality Analysis - Last 7 Days (Nov 14-21, 2025)
+
+## Summary
+- **Commits analyzed:** 30 commits
+- **Files changed:** 29 unique files
+- **Key areas:** DAM CLI, Configuration system, Project resolution, S3 operations
+- **Analysis date:** 2025-01-21
+
+### Commit Themes
+The last week focused heavily on:
+1. **Configuration loading fixes** (7x config load calls - commit 94d3ea0)
+2. **Brand resolution** (v- prefix handling)
+3. **DAM CLI UX improvements** (validation, table formatting, status displays)
+4. **Debug infrastructure** (DAM_DEBUG logging for remote debugging)
+5. **Project resolver** (regex capture group bug fix - commit 9e49668)
+
+## Critical Issues 🔴
+
+### 1. Code Duplication: Git Operations Helper Methods
+- **Found in:**
+  - `lib/appydave/tools/dam/status.rb:243-275` (4 methods)
+  - `lib/appydave/tools/dam/repo_status.rb:109-144` (6 methods)
+  - `lib/appydave/tools/dam/repo_push.rb:107-119` (3 methods)
+
+- **Description:** Three classes have nearly identical git helper methods:
+  ```ruby
+  # DUPLICATED across Status, RepoStatus, RepoPush:
+  def current_branch
+    `git -C "#{brand_path}" rev-parse --abbrev-ref HEAD 2>/dev/null`.strip
+  end
+
+  def commits_ahead
+    `git -C "#{brand_path}" rev-list --count @{upstream}..HEAD 2>/dev/null`.strip.to_i
+  end
+
+  def commits_behind
+    `git -C "#{brand_path}" rev-list --count HEAD..@{upstream} 2>/dev/null`.strip.to_i
+  end
+
+  # Plus: remote_url, modified_files_count, untracked_files_count, uncommitted_changes?
+  ```
+
+- **Impact:**
+  - **High maintenance burden** - Git command changes require updates in 3 places
+  - **Bug risk** - Bug fixes might miss one location
+  - **~90 lines duplicated** across 3 files
+  - **Testing burden** - Same behavior tested 3 times
+
+- **Recommendation:**
+  - Extract to `lib/appydave/tools/dam/git_helper.rb` module:
+    ```ruby
+    module Appydave::Tools::Dam::GitHelper
+      def current_branch(repo_path)
+        `git -C "#{repo_path}" rev-parse --abbrev-ref HEAD 2>/dev/null`.strip
+      end
+      # ... all other git methods
+    end
+    ```
+  - Mix into classes: `include GitHelper`
+  - Call: `current_branch(brand_path)`
+
+- **Estimated effort:** Medium (2-3 hours including tests)
+
+### 2. Code Duplication: Configuration Loading Pattern
+- **Found in:**
+  - `lib/appydave/tools/dam/config.rb` - 7 calls to `Config.configure`
+  - `lib/appydave/tools/dam/project_resolver.rb:144`
+  - `lib/appydave/tools/dam/status.rb:32`
+  - `lib/appydave/tools/dam/repo_status.rb:36,55`
+  - `lib/appydave/tools/dam/share_operations.rb:68`
+  - Plus 15+ more locations across DAM module
+
+- **Description:** `Appydave::Tools::Configuration::Config.configure` called repeatedly, often multiple times in the same method or class
+
+- **Pattern Example:**
+  ```ruby
+  # lib/appydave/tools/dam/config.rb:27-29
+  def brand_path(brand_key)
+    Appydave::Tools::Configuration::Config.configure  # ← Called
+    brand_info = Appydave::Tools::Configuration::Config.brands.get_brand(brand_key)
+    # ...
+  end
+
+  # lib/appydave/tools/dam/config.rb:51-52
+  def project_path(brand_key, project_id)
+    Appydave::Tools::Configuration::Config.configure  # ← Called again
+    brand_info = Appydave::Tools::Configuration::Config.brands.get_brand(brand_key)
+    # ...
+  end
+  ```
+
+- **Impact:**
+  - **Performance concern** - Config loaded 7+ times in tight loops (commit 94d3ea0 fixed this)
+  - **Code noise** - Reduces readability with repeated boilerplate
+  - **Unclear responsibility** - Is `Config.configure` idempotent? (Yes, but not obvious)
+
+- **Recommendation:**
+  - **Option A (Quick fix):** Call once per class in initializer/module load
+  - **Option B (Better):** Make `Config.configure` memoized singleton (already done in commit 94d3ea0)
+  - **Option C (Best):** Dependency injection - pass config objects instead of calling global
+
+- **Estimated effort:** Small (already partially fixed in 94d3ea0)
+
+### 3. Architectural Issue: Brand Resolution Logic Scattered
+- **Found in:**
+  - `lib/appydave/tools/dam/config.rb:91-116` (`expand_brand` method)
+  - `lib/appydave/tools/dam/project_resolver.rb:118-121` (regex capture + `.sub(/^v-/, '')`)
+  - `bin/dam` - Multiple inline brand validation checks
+
+- **Description:** Brand key transformation (`appydave` ↔ `v-appydave`) handled in multiple places with slightly different logic:
+  ```ruby
+  # Config.rb - lookup from brands.json
+  brand = brands_config.brands.find { |b| b.key.downcase == shortcut_str.downcase }
+  return "v-#{brand.key}" if brand
+
+  # ProjectResolver.rb - strip v- prefix
+  brand_key = brand_with_prefix.sub(/^v-/, '')
+
+  # Hardcoded shortcuts in Config.rb:111-114
+  case normalized
+  when 'joy' then 'v-beauty-and-joy'
+  when 'ss' then 'v-supportsignal'
+  ```
+
+- **Impact:**
+  - **Fragile** - Adding new brand shortcuts requires changes in multiple files
+  - **Inconsistent** - Some code assumes v- prefix, some doesn't
+  - **Hard to test** - Logic spread across multiple layers
+  - **Bug history** - Recent fixes (commits 94d3ea0, 771a20f, 3966f16) show ongoing confusion
+
+- **Recommendation:**
+  - Create `BrandResolver` class with clear responsibilities:
+    ```ruby
+    class BrandResolver
+      def self.expand(shortcut)    # appydave → v-appydave
+      def self.normalize(brand)     # v-appydave → appydave
+      def self.validate(brand)      # raises if invalid
+      def self.to_config_key(brand) # always returns key form (no v-)
+      def self.to_display(brand)    # always returns display form (v-)
+    end
+    ```
+  - Centralize all brand name transformations
+  - Document which methods expect which format
+
+- **Estimated effort:** Large (1-2 days including refactor + tests)
+
+## Moderate Issues 🟡
+
+### 1. Pattern Inconsistency: Config Loading in Tests
+- **Found in:**
+  - `spec/appydave/tools/dam/project_listing_spec.rb:23-29` (extensive mocking)
+  - `spec/appydave/tools/dam/project_resolver_spec.rb:304-307` (partial mocking)
+
+- **Pattern A (ProjectListingSpec):** Heavy mocking of Config class methods
+  ```ruby
+  allow(Appydave::Tools::Dam::Config).to receive_messages(
+    projects_root: temp_root,
+    available_brands: %w[appydave voz]
+  )
+  allow(Appydave::Tools::Dam::Config).to receive(:brand_path).with('appydave').and_return(brand1_path)
+  # 20 lines of allow() statements
+  ```
+
+- **Pattern B (ProjectResolverSpec):** Shared context with real filesystem
+  ```ruby
+  include_context 'with vat filesystem and brands', brands: %w[appydave voz]
+  # Uses actual temp directories, minimal mocking
+  ```
+
+- **Impact:**
+  - **Confusion** - New contributors don't know which pattern to use
+  - **Test brittleness** - Heavy mocking in ProjectListingSpec (20 mocks vs 252 lines = 8% mock density)
+  - **Maintenance burden** - Config changes break many mocks
+
+- **Recommendation:**
+  - **Standardize on Pattern B** - Real filesystem with shared contexts
+  - Refactor `project_listing_spec.rb` to use `with vat filesystem` context
+  - Reserve mocking for external services (S3, AWS) not internal DAM classes
+
+- **Estimated effort:** Medium (half day to refactor tests)
+
+### 2. Pattern Inconsistency: Error Handling
+- **Found in:**
+  - `lib/appydave/tools/dam/project_resolver.rb:19` - `raise '❌ Error message'`
+  - `lib/appydave/tools/dam/config_loader.rb:27` - `raise ConfigNotFoundError, <<~ERROR`
+  - `lib/appydave/tools/dam/share_operations.rb:175` - `raise ArgumentError, 'message'`
+  - `bin/dam` - Multiple `rescue StandardError => e` blocks with `puts` + `exit 1`
+
+- **Patterns:**
+  - **String errors:** `raise '❌ ...'` (ProjectResolver)
+  - **Custom exceptions:** `ConfigNotFoundError` (ConfigLoader)
+  - **Standard exceptions:** `ArgumentError` (ShareOperations)
+  - **CLI error handling:** `rescue → puts → exit` (bin/dam)
+
+- **Recommendation:**
+  - Define DAM-specific exception hierarchy:
+    ```ruby
+    module Appydave::Tools::Dam
+      class DamError < StandardError; end
+      class BrandNotFoundError < DamError; end
+      class ProjectNotFoundError < DamError; end
+      class ConfigurationError < DamError; end
+    end
+    ```
+  - Use consistently throughout DAM module
+  - Keep CLI-level `rescue StandardError` in bin/dam for user-friendly messages
+
+- **Estimated effort:** Small (few hours)
+
+### 3. Missing Abstraction: Directory Size Calculation
+- **Found in:**
+  - `lib/appydave/tools/dam/project_listing.rb:154-164`
+  - `lib/appydave/tools/dam/s3_operations.rb:770-778`
+  - `lib/appydave/tools/dam/sync_from_ssd.rb:270-278` (format_bytes)
+
+- **Description:** Same directory size calculation logic duplicated 3+ times
+
+- **Recommendation:**
+  - Extract to `lib/appydave/tools/dam/file_utils.rb`:
+    ```ruby
+    module FileUtils
+      def self.directory_size(path)
+      def self.format_size(bytes)
+    end
+    ```
+
+- **Estimated effort:** Small (1 hour)
+
+## Minor Observations 🔵
+
+### 1. Debugging Infrastructure (GOOD - Protected Pattern ✅)
+- **Found in:**
+  - `lib/appydave/tools/configuration/models/config_base.rb:33-58`
+  - `lib/appydave/tools/dam/project_resolver.rb:149,153`
+  - Multiple `puts "DEBUG: ..."` statements
+
+- **Description:** DAM_DEBUG and DEBUG env var support added for remote debugging (commit 8844aa9)
+
+- **Impact:** **Positive** - Essential for production debugging
+
+- **Recommendation:** **Keep as-is** - This is intentional defensive programming, not code bloat
+
+### 2. Regex Capture Group Bug Fixed
+- **Fixed in:** commit 9e49668
+- **Issue:** `Regexp.last_match` reset by `.sub()` call
+- **Solution:** Capture before transformation
+  ```ruby
+  project = Regexp.last_match(2)  # Capture BEFORE
+  brand_key = brand_with_prefix.sub(/^v-/, '')  # Then modify
+  ```
+
+- **Impact:** **Positive** - Proper fix, not hidden with mocks
+
+## Positive Patterns ✅
+
+### 1. Test Organization with Shared Contexts
+- **Found in:** `spec/appydave/tools/dam/project_resolver_spec.rb`
+- **Why it's good:**
+  - Uses `include_context 'with vat filesystem and brands'`
+  - Real temp directories, minimal mocking
+  - Tests actual behavior, not implementation details
+  - Easy to understand and maintain
+
+- **Recommend:** Use this pattern for all DAM specs
+
+### 2. Configuration Debug Logging
+- **Found in:** `lib/appydave/tools/configuration/models/config_base.rb`
+- **Why it's good:**
+  - Toggleable with DAM_DEBUG env var
+  - Shows config load path, file existence, parse errors
+  - Includes JSON output for verification
+  - Essential for remote debugging production issues
+
+- **Recommend:** Continue this pattern for all critical configuration paths
+
+### 3. Defensive Nil Checking
+- **Found in:** commit a205319
+- **Example:**
+  ```ruby
+  def resolve(brand, project_hint)
+    raise '❌ Project name is required' if project_hint.nil? || project_hint.empty?
+  ```
+
+- **Why it's good:** Prevents cryptic `include?` errors on nil
+- **Recommend:** Add similar guards to all public methods expecting non-nil arguments
+
+## Prioritized Action Items
+
+### High Priority (Do First)
+1. [ ] **Extract GitHelper module** - Eliminate 90 lines of duplication (status.rb, repo_status.rb, repo_push.rb)
+   - lib/appydave/tools/dam/git_helper.rb:1
+2. [ ] **Create BrandResolver abstraction** - Centralize brand transformation logic
+   - lib/appydave/tools/dam/brand_resolver.rb:1
+3. [ ] **Refactor project_listing_spec.rb** - Use shared filesystem context instead of 20 mocks
+   - spec/appydave/tools/dam/project_listing_spec.rb:1
+
+### Medium Priority (Do Soon)
+1. [ ] **Define DAM exception hierarchy** - Replace string raises with typed exceptions
+   - lib/appydave/tools/dam/errors.rb:1
+2. [ ] **Extract FileUtils helpers** - Consolidate directory_size and format_size methods
+   - lib/appydave/tools/dam/file_utils.rb:1
+3. [ ] **Document Config.configure memoization** - Add comment explaining idempotent behavior
+   - lib/appydave/tools/configuration/config.rb:15
+
+### Low Priority (Future Improvement)
+1. [ ] **Add integration tests** - Test brand resolution end-to-end across modules
+2. [ ] **Extract CLI argument parsing** - bin/dam has 200+ line methods, extract parsers
+3. [ ] **Consider dependency injection** - Pass config objects instead of global Config calls
+
+## Statistics
+- **Total duplicated code:** ~150 lines (90 git methods + 40 directory utils + 20 config calls)
+- **Test mock density:** ProjectListingSpec: 20 mocks / 252 lines = 8% (acceptable, but could improve)
+- **Pattern inconsistencies:** 3 error handling patterns, 2 test patterns
+- **Large methods:** bin/dam has multiple 50+ line methods (help commands, parsers)
+- **Configuration loading:** Fixed in commit 94d3ea0 (7x redundant calls → memoized singleton)
+
+## Analysis Methodology
+
+### Commands Used:
+```bash
+# Discovery
+git log --since="7 days ago" --pretty=format:"%h - %s (%an, %ar)"
+git log --since="7 days ago" --name-only | sort | uniq -c | sort -rn
+
+# Duplication detection
+grep -rn "def.*brand.*path" lib/appydave/tools/dam/
+grep -rn "git -C.*rev-parse|git -C.*rev-list" lib/appydave/tools/dam/
+grep -c "allow.*to receive|double|instance_double" spec/appydave/tools/dam/*.rb
+
+# File analysis
+find lib/appydave/tools/dam -name "*.rb" -exec wc -l {} \;
+```
+
+### Files Analyzed:
+- 12 DAM module files (config.rb, project_resolver.rb, status.rb, repo_status.rb, s3_operations.rb, etc.)
+- 7 spec files
+- bin/dam CLI script
+- Configuration system files
+
+---
+
+**Report Generated:** 2025-01-21 by Claude Code Quality Retrospective Analysis

data/lib/appydave/tools/dam/brand_resolver.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+module Appydave
+  module Tools
+    module Dam
+      # Centralized brand name resolution and transformation
+      #
+      # Handles conversion between:
+      # - Shortcuts: 'appydave', 'ad', 'joy', 'ss'
+      # - Config keys: 'appydave', 'beauty-and-joy', 'supportsignal'
+      # - Display names: 'v-appydave', 'v-beauty-and-joy', 'v-supportsignal'
+      #
+      # @example
+      #   BrandResolver.expand('ad')          # => 'v-appydave'
+      #   BrandResolver.normalize('v-voz')    # => 'voz'
+      #   BrandResolver.to_config_key('ad')   # => 'appydave'
+      #   BrandResolver.to_display('voz')     # => 'v-voz'
+      class BrandResolver
+        class << self
+          # Expand shortcut or key to full display name
+          # @param shortcut [String] Brand shortcut or key
+          # @return [String] Full brand name with v- prefix
+          def expand(shortcut)
+            return shortcut.to_s if shortcut.to_s.start_with?('v-')
+
+            key = to_config_key(shortcut)
+            "v-#{key}"
+          end
+
+          # Normalize brand name to config key (strip v- prefix)
+          # @param brand [String] Brand name (with or without v-)
+          # @return [String] Config key without v- prefix
+          def normalize(brand)
+            brand.to_s.sub(/^v-/, '')
+          end
+
+          # Convert to config key (handles shortcuts)
+          # @param input [String] Shortcut, key, or display name
+          # @return [String] Config key
+          def to_config_key(input)
+            # Strip v- prefix first
+            normalized = normalize(input)
+
+            # Look up from brands.json
+            Appydave::Tools::Configuration::Config.configure
+            brands_config = Appydave::Tools::Configuration::Config.brands
+
+            # Check if matches brand key (case-insensitive)
+            brand = brands_config.brands.find { |b| b.key.downcase == normalized.downcase }
+            return brand.key if brand
+
+            # Check if matches shortcut (case-insensitive)
+            brand = brands_config.brands.find { |b| b.shortcut.downcase == normalized.downcase }
+            return brand.key if brand
+
+            # Fall back to hardcoded shortcuts (backward compatibility)
+            case normalized.downcase
+            when 'ad' then 'appydave'
+            when 'joy' then 'beauty-and-joy'
+            when 'ss' then 'supportsignal'
+            else
+              normalized.downcase
+            end
+          end
+
+          # Convert to display name (always v- prefix)
+          # @param input [String] Shortcut, key, or display name
+          # @return [String] Display name with v- prefix
+          def to_display(input)
+            expand(input)
+          end
+
+          # Validate brand exists in filesystem
+          # @param brand [String] Brand to validate
+          # @raise [BrandNotFoundError] if brand invalid
+          # @return [String] Config key if valid
+          def validate(brand)
+            key = to_config_key(brand)
+
+            # Build brand path (avoiding circular dependency with Config.brand_path)
+            Appydave::Tools::Configuration::Config.configure
+            brand_info = Appydave::Tools::Configuration::Config.brands.get_brand(key)
+
+            # If brand has configured video_projects path, use it
+            if brand_info.locations.video_projects && !brand_info.locations.video_projects.empty?
+              brand_path = brand_info.locations.video_projects
+            else
+              # Fall back to projects_root + expanded brand name
+              root = Config.projects_root
+              brand_path = File.join(root, expand(key))
+            end
+
+            unless Dir.exist?(brand_path)
+              available = Config.available_brands_display
+              raise BrandNotFoundError.new(brand, available)
+            end
+
+            key
+          rescue StandardError => e
+            raise BrandNotFoundError, e.message unless e.is_a?(BrandNotFoundError)
+
+            raise
+          end
+
+          # Check if brand exists (returns boolean instead of raising)
+          # @param brand [String] Brand to check
+          # @return [Boolean] true if brand exists
+          def exists?(brand)
+            validate(brand)
+            true
+          rescue BrandNotFoundError
+            false
+          end
+        end
+      end
+    end
+  end
+end

data/lib/appydave/tools/dam/config.rb

@@ -85,34 +85,11 @@ module Appydave
           end
 
           # Expand brand shortcut to full brand name
-          # Reads from brands.json if available, falls back to hardcoded shortcuts
+          # Delegates to BrandResolver for centralized brand resolution
           # @param shortcut [String] Brand shortcut (e.g., 'appydave', 'ad', 'APPYDAVE')
           # @return [String] Full brand name (e.g., 'v-appydave')
           def expand_brand(shortcut)
-            shortcut_str = shortcut.to_s
-
-            return shortcut_str if shortcut_str.start_with?('v-')
-
-            # Try to read from brands.json
-            Appydave::Tools::Configuration::Config.configure
-            brands_config = Appydave::Tools::Configuration::Config.brands
-
-            # Check if input matches a brand key (case-insensitive)
-            brand = brands_config.brands.find { |b| b.key.downcase == shortcut_str.downcase }
-            return "v-#{brand.key}" if brand
-
-            # Check if input matches a brand shortcut (case-insensitive)
-            brand = brands_config.brands.find { |b| b.shortcut.downcase == shortcut_str.downcase }
-            return "v-#{brand.key}" if brand
-
-            # Fall back to hardcoded shortcuts for backwards compatibility
-            normalized = shortcut_str.downcase
-            case normalized
-            when 'joy' then 'v-beauty-and-joy'
-            when 'ss' then 'v-supportsignal'
-            else
-              "v-#{normalized}"
-            end
+            BrandResolver.expand(shortcut)
           end
 
           # Get list of available brands

data/lib/appydave/tools/dam/errors.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Appydave
+  module Tools
+    module Dam
+      # Base error for all DAM operations
+      class DamError < StandardError; end
+
+      # Raised when brand directory not found
+      class BrandNotFoundError < DamError
+        def initialize(brand, available_brands = nil)
+          message = "Brand directory not found: #{brand}"
+          message += "\n\nAvailable brands:\n#{available_brands}" if available_brands && !available_brands.empty?
+          super(message)
+        end
+      end
+
+      # Raised when project not found in brand
+      class ProjectNotFoundError < DamError; end
+
+      # Raised when configuration invalid or missing
+      class ConfigurationError < DamError; end
+
+      # Raised when S3 operation fails
+      class S3OperationError < DamError; end
+
+      # Raised when git operation fails
+      class GitOperationError < DamError; end
+    end
+  end
+end

data/lib/appydave/tools/dam/file_helper.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require 'find'
+
+module Appydave
+  module Tools
+    module Dam
+      # File utility methods for DAM operations
+      # Provides reusable file and directory helpers
+      module FileHelper
+        module_function
+
+        # Calculate total size of directory in bytes
+        # @param path [String] Directory path
+        # @return [Integer] Size in bytes
+        def calculate_directory_size(path)
+          return 0 unless Dir.exist?(path)
+
+          total = 0
+          Find.find(path) do |file_path|
+            total += File.size(file_path) if File.file?(file_path)
+          rescue StandardError
+            # Skip files we can't read
+          end
+          total
+        end
+
+        # Format bytes into human-readable size
+        # @param bytes [Integer] Size in bytes
+        # @return [String] Formatted size (e.g., "1.5 GB")
+        def format_size(bytes)
+          return '0 B' if bytes.zero?
+
+          units = %w[B KB MB GB TB]
+          exp = (Math.log(bytes) / Math.log(1024)).to_i
+          exp = [exp, units.length - 1].min
+
+          format('%<size>.1f %<unit>s', size: bytes.to_f / (1024**exp), unit: units[exp])
+        end
+      end
+    end
+  end
+end

data/lib/appydave/tools/dam/git_helper.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+module Appydave
+  module Tools
+    module Dam
+      # Git operations helper for DAM classes
+      # Provides reusable git command wrappers
+      module GitHelper
+        module_function
+
+        # Get current branch name
+        # @param repo_path [String] Path to git repository
+        # @return [String] Branch name or 'unknown' if error
+        def current_branch(repo_path)
+          result = `git -C "#{repo_path}" rev-parse --abbrev-ref HEAD 2>/dev/null`.strip
+          result.empty? ? 'unknown' : result
+        rescue StandardError
+          'unknown'
+        end
+
+        # Get git remote URL
+        # @param repo_path [String] Path to git repository
+        # @return [String, nil] Remote URL or nil if not configured
+        def remote_url(repo_path)
+          result = `git -C "#{repo_path}" remote get-url origin 2>/dev/null`.strip
+          result.empty? ? nil : result
+        rescue StandardError
+          nil
+        end
+
+        # Count commits ahead of remote
+        # @param repo_path [String] Path to git repository
+        # @return [Integer] Number of commits ahead
+        def commits_ahead(repo_path)
+          `git -C "#{repo_path}" rev-list --count @{upstream}..HEAD 2>/dev/null`.strip.to_i
+        rescue StandardError
+          0
+        end
+
+        # Count commits behind remote
+        # @param repo_path [String] Path to git repository
+        # @return [Integer] Number of commits behind
+        def commits_behind(repo_path)
+          `git -C "#{repo_path}" rev-list --count HEAD..@{upstream} 2>/dev/null`.strip.to_i
+        rescue StandardError
+          0
+        end
+
+        # Count modified files
+        # @param repo_path [String] Path to git repository
+        # @return [Integer] Number of modified files
+        def modified_files_count(repo_path)
+          `git -C "#{repo_path}" status --porcelain 2>/dev/null | grep -E "^.M|^M" | wc -l`.strip.to_i
+        rescue StandardError
+          0
+        end
+
+        # Count untracked files
+        # @param repo_path [String] Path to git repository
+        # @return [Integer] Number of untracked files
+        def untracked_files_count(repo_path)
+          `git -C "#{repo_path}" status --porcelain 2>/dev/null | grep -E "^\\?\\?" | wc -l`.strip.to_i
+        rescue StandardError
+          0
+        end
+
+        # Check if repository has uncommitted changes
+        # @param repo_path [String] Path to git repository
+        # @return [Boolean] true if changes exist
+        def uncommitted_changes?(repo_path)
+          system("git -C \"#{repo_path}\" diff-index --quiet HEAD -- 2>/dev/null")
+          !$CHILD_STATUS.success?
+        rescue StandardError
+          false
+        end
+
+        # Fetch from remote
+        # @param repo_path [String] Path to git repository
+        # @return [Boolean] true if successful
+        def fetch(repo_path)
+          system("git -C \"#{repo_path}\" fetch 2>/dev/null")
+          $CHILD_STATUS.success?
+        rescue StandardError
+          false
+        end
+      end
+    end
+  end
+end