appydave-tools 0.38.0 → 0.40.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ca0b626390693cf429dec2da61dca877811720aed92dd110849a826bbe53f3fe
-  data.tar.gz: fba4176a5c363b7578409d63a6119f495138d637c9e03f309830317fb351ba2a
+  metadata.gz: 9610c23fa022740f9082e2bd0086bf7727cfe96437309b099a1bc5fbe55f58ea
+  data.tar.gz: d556ee4ced131cfc9f7b8244edf9c2c464d5d3692a669cb0f7102831fccf1689
 SHA512:
-  metadata.gz: 7fac67c172b7153c59aee5d9a0d845c9bac1cc77040068472e125a850295435f625626addd49becded1b52e81db53d6d206269610c807e5a318a71e3647a0b08
-  data.tar.gz: 936903137cf045758a3d131a3254e6ff44eca468455b546e5c98b55eb516242a7d861139e20cc75331e41cee256a3ff34a233c9ba2d6d67833ac8f1a245d570a
+  metadata.gz: f337f930defe037888a8ebc8dd19f6562519b39170b33a8944e68cc050059a65902d41c788d6cafa2c6132b2d2ee6f408ad54a420ce68c1bb74fb392ab9dc716
+  data.tar.gz: f7f0933afa44c8e3a79aa3ceb6b53db950d0acb9e3b5ba17daf3acc46eafc97afd19071c0e335485d3345c08c9218c2285f5dcc0f74332bd87a3bf136a7dc210

data/CHANGELOG.md

@@ -1,3 +1,24 @@
+# [0.39.0](https://github.com/appydave/appydave-tools/compare/v0.38.0...v0.39.0) (2025-11-21)
+
+
+### Features
+
+* create BrandResolver class to centralize brand name resolution and eliminate ~30 lines of duplication from Config.expand_brand, fixing case-sensitivity bugs ([d6cce4b](https://github.com/appydave/appydave-tools/commit/d6cce4b0c1df6d7efcd40db52e80534c4014fdb5))
+
+# [0.38.0](https://github.com/appydave/appydave-tools/compare/v0.37.0...v0.38.0) (2025-11-21)
+
+
+### Bug Fixes
+
+* rename FileUtils to FileHelper to avoid Ruby stdlib conflict ([e441b43](https://github.com/appydave/appydave-tools/commit/e441b4356ec40a66f5562e9cf0ec74f562b449b2))
+
+
+### Features
+
+* add DAM exception hierarchy for consistent error handling ([c885590](https://github.com/appydave/appydave-tools/commit/c885590be721d2b2803fd6aaa7001afc8cdbd285))
+* extract FileUtils module to eliminate 40 lines of duplication ([643748e](https://github.com/appydave/appydave-tools/commit/643748ea583eba3605e1a6ce17e117db18f66c4c))
+* extract GitHelper module to eliminate ~90 lines of git operations duplication across status.rb, repo_status.rb, and repo_push.rb ([f32dc1d](https://github.com/appydave/appydave-tools/commit/f32dc1d54877a9a981878a6e7c203922e50004fe))
+
 # [0.37.0](https://github.com/appydave/appydave-tools/compare/v0.36.0...v0.37.0) (2025-11-21)
 
 

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

@@ -3,7 +3,33 @@
 module Appydave
   module Tools
     module Configuration
-      # Configuration class for handling multiple configurations
+      # Central configuration management for appydave-tools
+      #
+      # Thread-safe singleton pattern with memoization for registered configurations.
+      # Calling `Config.configure` multiple times is safe and idempotent.
+      #
+      # @example Basic usage
+      #   Config.configure  # Load default configuration (idempotent)
+      #   Config.settings.video_projects_root  # Access settings
+      #   Config.brands.get_brand('appydave')  # Access brands
+      #
+      # @example DAM module usage pattern
+      #   # Config.configure called once at module load time
+      #   # All subsequent calls within DAM classes are no-ops (memoized)
+      #   def some_method
+      #     Config.configure  # Safe to call - returns immediately if already configured
+      #     brand = Config.brands.get_brand('appydave')
+      #   end
+      #
+      # @example Registered configurations
+      #   Config.settings         # => SettingsConfig instance
+      #   Config.brands           # => BrandsConfig instance
+      #   Config.channels         # => ChannelsConfig instance
+      #   Config.youtube_automation  # => YoutubeAutomationConfig instance
+      #
+      # @note Configuration instances are created once on first registration and reused
+      #   for all subsequent accesses. This prevents unnecessary file I/O and ensures
+      #   consistent state across the application.
       class Config
         class << self
           include KLog::Logging
@@ -12,6 +38,25 @@ module Appydave
           attr_reader :configurations
           attr_reader :default_block
 
+          # Load configuration using either provided block or default configuration
+          #
+          # This method is idempotent and thread-safe. Calling it multiple times
+          # has no negative side effects - configurations are memoized on first call.
+          #
+          # @yield [Config] configuration object for manual setup
+          # @return [void]
+          # @raise [Error] if no block provided and no default_block set
+          #
+          # @example With block (manual configuration)
+          #   Config.configure do |config|
+          #     config.config_path = '/custom/path'
+          #     config.register(:settings, SettingsConfig)
+          #   end
+          #
+          # @example Without block (uses default_block)
+          #   Config.set_default { |config| config.register(:settings, SettingsConfig) }
+          #   Config.configure  # Uses default_block
+          #   Config.configure  # Safe to call again - no-op due to memoization
           def configure
             if block_given?
               yield self
@@ -23,6 +68,23 @@ module Appydave
             ensure_config_directory
           end
 
+          # Register a configuration class with memoization
+          #
+          # Creates a single instance of the configuration class on first call.
+          # Subsequent calls return the same instance (memoized). This prevents
+          # unnecessary file I/O and ensures consistent configuration state.
+          #
+          # @param key [Symbol] configuration identifier (e.g., :settings, :brands)
+          # @param klass [Class] configuration class to instantiate
+          # @return [Object] configuration instance
+          #
+          # @example
+          #   Config.register(:settings, SettingsConfig)
+          #   Config.settings  # => SettingsConfig instance (created on first access)
+          #   Config.settings  # => Same instance (memoized)
+          #
+          # @note This method implements lazy initialization - the configuration
+          #   instance is only created when first accessed, not at registration time.
           def register(key, klass)
             @configurations ||= {}
             # Only create new instance if not already registered (prevents multiple reloads)
@@ -30,10 +92,26 @@ module Appydave
           end
 
           # Reset all configurations (primarily for testing)
+          #
+          # Clears all memoized configuration instances. Use this in test teardown
+          # to ensure each test starts with a clean configuration state.
+          #
+          # @return [void]
+          #
+          # @example RSpec usage
+          #   after { Config.reset }
           def reset
             @configurations = nil
           end
 
+          # Dynamic accessor for registered configurations
+          #
+          # Provides method-style access to registered configuration instances.
+          # Called when accessing Config.settings, Config.brands, etc.
+          #
+          # @param method_name [Symbol] configuration key
+          # @return [Object] configuration instance
+          # @raise [Error] if configurations not registered or key not found
           def method_missing(method_name, *_args)
             raise Appydave::Tools::Error, 'Configuration has never been registered' if @configurations.nil?
             raise Appydave::Tools::Error, "Configuration not available: #{method_name}" unless @configurations.key?(method_name)
@@ -45,18 +123,27 @@ module Appydave
             @configurations.key?(method_name) || super
           end
 
+          # Save all registered configurations to their respective files
+          # @return [void]
           def save
             configurations.each_value(&:save)
           end
 
+          # Set default configuration block used when configure called without block
+          # @yield [Config] configuration block to execute by default
+          # @return [Proc] the stored block
           def set_default(&block)
             @default_block = block
           end
 
+          # Load all registered configurations from their respective files
+          # @return [void]
           def load
             configurations.each_value(&:load)
           end
 
+          # Open configuration directory in VS Code
+          # @return [void]
           def edit
             ensure_config_directory
             puts "Edit configuration: #{config_path}"
@@ -64,6 +151,8 @@ module Appydave
             Open3.capture3(open_vscode)
           end
 
+          # Debug output for all configurations
+          # @return [void]
           def debug
             log.kv 'Configuration Path', config_path
             configurations.each_value(&:debug)
@@ -74,6 +163,9 @@ module Appydave
           #   configurations.each_value(&:print)
           # end
 
+          # Print specific configurations or all if no keys provided
+          # @param keys [Array<String, Symbol>] configuration keys to print
+          # @return [void]
           def print(*keys)
             if keys.empty?
               keys = configurations.keys

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/project_resolver.rb

@@ -116,9 +116,9 @@ module Appydave
             # Check if we're inside a v-* directory
             if current =~ %r{/(v-[^/]+)/([^/]+)/?}
               brand_with_prefix = ::Regexp.last_match(1)
-              project = ::Regexp.last_match(2) # Capture BEFORE .sub() which resets Regexp.last_match
+              project = ::Regexp.last_match(2) # Capture BEFORE normalize() which resets Regexp.last_match
               # Strip 'v-' prefix to get brand key (e.g., 'v-supportsignal' → 'supportsignal')
-              brand_key = brand_with_prefix.sub(/^v-/, '')
+              brand_key = BrandResolver.normalize(brand_with_prefix)
               return [brand_key, project] if project_exists?(brand_key, project)
             end
 

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

@@ -140,6 +140,7 @@ module Appydave
           skipped = 0
           failed = 0
 
+          # rubocop:disable Metrics/BlockLength
           files.each do |file|
             relative_path = file.sub("#{staging_dir}/", '')
 
@@ -158,12 +159,31 @@ module Appydave
             if local_md5 == s3_md5
               puts "  ⏭️  Skipped: #{relative_path} (unchanged)"
               skipped += 1
-            elsif upload_file(file, s3_path, dry_run: dry_run)
-              uploaded += 1
             else
-              failed += 1
+              # Warn if we're about to overwrite an existing S3 file
+              if s3_md5 && s3_md5 != local_md5
+                puts "  ⚠️  Warning: #{relative_path} exists in S3 with different content"
+
+                # Try to get S3 timestamp for comparison
+                s3_file_info = get_s3_file_info(s3_path)
+                if s3_file_info && s3_file_info['LastModified']
+                  s3_time = s3_file_info['LastModified']
+                  local_time = File.mtime(file)
+                  puts "     S3: #{s3_time.strftime('%Y-%m-%d %H:%M')} | Local: #{local_time.strftime('%Y-%m-%d %H:%M')}"
+
+                  puts '     ⚠️  S3 file is NEWER than local - you may be overwriting recent changes!' if s3_time > local_time
+                end
+                puts '     Uploading will overwrite S3 version...'
+              end
+
+              if upload_file(file, s3_path, dry_run: dry_run)
+                uploaded += 1
+              else
+                failed += 1
+              end
             end
           end
+          # rubocop:enable Metrics/BlockLength
 
           puts ''
           puts '✅ Upload complete!'
@@ -207,13 +227,29 @@ module Appydave
             if local_md5 == s3_md5
               puts "  ⏭️  Skipped: #{relative_path} (unchanged)"
               skipped += 1
-            elsif download_file(key, local_file, dry_run: dry_run)
-              downloaded += 1
             else
-              failed += 1
+              # Warn if we're about to overwrite an existing local file
+              if local_md5 && local_md5 != s3_md5
+                puts "  ⚠️  Warning: #{relative_path} exists locally with different content"
+
+                # Compare timestamps
+                if s3_file['LastModified'] && File.exist?(local_file)
+                  s3_time = s3_file['LastModified']
+                  local_time = File.mtime(local_file)
+                  puts "     S3: #{s3_time.strftime('%Y-%m-%d %H:%M')} | Local: #{local_time.strftime('%Y-%m-%d %H:%M')}"
+
+                  puts '     ⚠️  Local file is NEWER than S3 - you may be overwriting recent changes!' if local_time > s3_time
+                end
+                puts '     Downloading will overwrite local version...'
+              end
+
+              if download_file(key, local_file, dry_run: dry_run)
+                downloaded += 1
+              else
+                failed += 1
+              end
             end
           end
-
           puts ''
           puts '✅ Download complete!'
           puts "   Downloaded: #{downloaded}, Skipped: #{skipped}, Failed: #{failed}"
@@ -634,13 +670,31 @@ module Appydave
             {
               'Key' => obj.key,
               'Size' => obj.size,
-              'ETag' => obj.etag
+              'ETag' => obj.etag,
+              'LastModified' => obj.last_modified
             }
           end
         rescue Aws::S3::Errors::ServiceError
           []
         end
 
+        # Get full S3 file info including timestamp
+        def get_s3_file_info(s3_key)
+          response = s3_client.head_object(
+            bucket: brand_info.aws.s3_bucket,
+            key: s3_key
+          )
+
+          {
+            'Key' => s3_key,
+            'Size' => response.content_length,
+            'ETag' => response.etag,
+            'LastModified' => response.last_modified
+          }
+        rescue Aws::S3::Errors::NotFound, Aws::S3::Errors::ServiceError
+          nil
+        end
+
         # List local files in staging directory
         def list_local_files(staging_dir)
           return {} unless Dir.exist?(staging_dir)

data/lib/appydave/tools/version.rb

@@ -2,6 +2,6 @@
 
 module Appydave
   module Tools
-    VERSION = '0.38.0'
+    VERSION = '0.40.0'
   end
 end

data/lib/appydave/tools.rb

@@ -55,6 +55,7 @@ require 'appydave/tools/subtitle_processor/join'
 require 'appydave/tools/dam/errors'
 require 'appydave/tools/dam/file_helper'
 require 'appydave/tools/dam/git_helper'
+require 'appydave/tools/dam/brand_resolver'
 require 'appydave/tools/dam/config'
 require 'appydave/tools/dam/project_resolver'
 require 'appydave/tools/dam/config_loader'

data/package.json

@@ -1,6 +1,6 @@
 {
   "name": "appydave-tools",
-  "version": "0.38.0",
+  "version": "0.40.0",
   "description": "AppyDave YouTube Automation Tools",
   "scripts": {
     "release": "semantic-release"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: appydave-tools
 version: !ruby/object:Gem::Version
-  version: 0.38.0
+  version: 0.40.0
 platform: ruby
 authors:
 - David Cruwys
@@ -297,6 +297,7 @@ files:
 - lib/appydave/tools/configuration/models/settings_config.rb
 - lib/appydave/tools/configuration/models/youtube_automation_config.rb
 - lib/appydave/tools/configuration/openai.rb
+- lib/appydave/tools/dam/brand_resolver.rb
 - lib/appydave/tools/dam/config.rb
 - lib/appydave/tools/dam/config_loader.rb
 - lib/appydave/tools/dam/errors.rb