appydave-tools 0.36.0 → 0.37.0

data/docs/ai-instructions/defensive-logging-audit.md

@@ -0,0 +1,802 @@
+# Defensive Logging Strategy Audit
+
+## Objective
+Ensure the codebase has sufficient logging infrastructure for remote debugging, especially around nil exceptions and configuration issues. This is particularly critical for internal tools used by remote team members where configuration problems are hard to diagnose.
+
+## Context
+This is a Ruby gem project (`appydave-tools`) that provides CLI tools for YouTube content creation workflows. It's used by multiple team members with different system configurations. Recent issues:
+
+- **The Jan Problem:** Remote user had configuration issues that were hard to debug because errors were opaque ("undefined method for nil:NilClass" without context about which configuration value was nil or where it was accessed)
+- **Configuration Hell:** Multiple configuration sources (settings.json, channels.json, .env files) make it hard to trace where values come from
+- **Path Resolution:** Brand/project path logic fails silently when paths don't exist or are misconfigured
+
+## Why This Matters
+**Ruby's nil exceptions are the worst:** `undefined method 'X' for nil:NilClass` tells you almost nothing about:
+- Which object was nil
+- Where it was supposed to be set
+- What configuration or method call led to the nil
+- What the system state was at the time
+
+**Defensive logging solves this:** With proper logging, errors become: "Failed to resolve brand 'appydave': settings.json missing video-projects-root at line 23 in BrandResolver#resolve_path"
+
+## Analysis Process
+
+### Phase 1: Configuration Loading Audit
+
+**Focus areas:**
+- `lib/appydave/tools/configuration/` (all config loading)
+- DAM configuration (settings.json parsing)
+- Channel configuration (channels.json parsing)
+- Environment variables (.env loading)
+
+**What to check:**
+
+1. **Configuration file loading:**
+   ```ruby
+   # ❌ BAD: Silent failure
+   def load_config
+     JSON.parse(File.read(config_path))
+   rescue => e
+     {}
+   end
+
+   # ✅ GOOD: Logged failure with context
+   def load_config
+     log.debug("Loading config from: #{config_path}")
+     config = JSON.parse(File.read(config_path))
+     log.debug("Config loaded successfully: #{config.keys.join(', ')}")
+     config
+   rescue Errno::ENOENT => e
+     log.error("Config file not found: #{config_path}")
+     log.error("Current directory: #{Dir.pwd}")
+     log.error("Expected location: #{File.expand_path(config_path)}")
+     raise ConfigurationError, "Missing config file: #{config_path}"
+   rescue JSON::ParserError => e
+     log.error("Invalid JSON in config file: #{config_path}")
+     log.error("Parse error: #{e.message}")
+     log.error("Check file syntax at: #{config_path}")
+     raise ConfigurationError, "Invalid JSON in #{config_path}: #{e.message}"
+   end
+   ```
+
+2. **Configuration value access:**
+   ```ruby
+   # ❌ BAD: Will blow up with opaque nil error
+   def video_projects_root
+     config['video-projects-root']
+   end
+
+   # ✅ GOOD: Explicit nil check with helpful error
+   def video_projects_root
+     value = config['video-projects-root']
+     if value.nil?
+       log.error("Missing 'video-projects-root' in settings.json")
+       log.error("Available keys: #{config.keys.join(', ')}")
+       log.error("Config file location: #{config_path}")
+       raise ConfigurationError, "Missing 'video-projects-root' in settings.json. Run 'ad_config -e' to set it."
+     end
+     log.debug("video-projects-root: #{value}")
+     value
+   end
+   ```
+
+3. **Configuration echo on startup:**
+   ```ruby
+   # ✅ GOOD: Log loaded configuration (sanitized)
+   def initialize
+     log.debug("=== Configuration Loaded ===")
+     log.debug("Config file: #{config_path}")
+     log.debug("Settings: #{sanitize_config(config).inspect}")
+     log.debug("Environment: #{ENV['DAM_DEBUG'] ? 'DEBUG' : 'PRODUCTION'}")
+     log.debug("===========================")
+   end
+
+   def sanitize_config(config)
+     # Remove sensitive values before logging
+     config.reject { |k, _| k.include?('token') || k.include?('secret') }
+   end
+   ```
+
+### Phase 2: Path Resolution Audit
+
+**Focus areas:**
+- Brand resolution (appydave → v-appydave)
+- Project path construction
+- File path validation
+- Directory existence checks
+
+**What to check:**
+
+1. **Brand resolution:**
+   ```ruby
+   # ❌ BAD: Silent failure if brand not found
+   def resolve_brand(brand_name)
+     BRAND_MAP[brand_name]
+   end
+
+   # ✅ GOOD: Logged resolution with fallback
+   def resolve_brand(brand_name)
+     log.debug("Resolving brand: #{brand_name}")
+
+     # Try exact match
+     if BRAND_MAP.key?(brand_name)
+       result = BRAND_MAP[brand_name]
+       log.debug("Brand resolved (exact): #{brand_name} → #{result}")
+       return result
+     end
+
+     # Try case-insensitive
+     key = BRAND_MAP.keys.find { |k| k.downcase == brand_name.downcase }
+     if key
+       result = BRAND_MAP[key]
+       log.debug("Brand resolved (case-insensitive): #{brand_name} → #{result}")
+       return result
+     end
+
+     # Failed
+     log.error("Brand not found: #{brand_name}")
+     log.error("Available brands: #{BRAND_MAP.keys.join(', ')}")
+     raise BrandNotFoundError, "Unknown brand: #{brand_name}. Available: #{BRAND_MAP.keys.join(', ')}"
+   end
+   ```
+
+2. **Path construction:**
+   ```ruby
+   # ❌ BAD: Will blow up if nil with no context
+   def project_path(brand, project_name)
+     File.join(video_projects_root, brand_folder(brand), project_name)
+   end
+
+   # ✅ GOOD: Validate inputs and log construction
+   def project_path(brand, project_name)
+     log.debug("Constructing project path: brand=#{brand}, project=#{project_name}")
+
+     root = video_projects_root
+     if root.nil?
+       log.error("video_projects_root is nil - check settings.json")
+       raise ConfigurationError, "Missing video-projects-root configuration"
+     end
+
+     folder = brand_folder(brand)
+     if folder.nil?
+       log.error("brand_folder returned nil for brand: #{brand}")
+       raise BrandError, "Could not resolve brand folder for: #{brand}"
+     end
+
+     path = File.join(root, folder, project_name)
+     log.debug("Project path constructed: #{path}")
+     path
+   end
+   ```
+
+3. **File/directory validation:**
+   ```ruby
+   # ❌ BAD: Assumes path exists
+   def read_project_file(path)
+     File.read(path)
+   end
+
+   # ✅ GOOD: Validate and log
+   def read_project_file(path)
+     log.debug("Reading project file: #{path}")
+
+     unless File.exist?(path)
+       log.error("File not found: #{path}")
+       log.error("Parent directory exists: #{File.directory?(File.dirname(path))}")
+       log.error("Current directory: #{Dir.pwd}")
+       raise FileNotFoundError, "Project file not found: #{path}"
+     end
+
+     content = File.read(path)
+     log.debug("File read successfully: #{content.bytesize} bytes")
+     content
+   rescue Errno::EACCES => e
+     log.error("Permission denied reading file: #{path}")
+     log.error("File permissions: #{File.stat(path).mode.to_s(8)}")
+     raise PermissionError, "Cannot read #{path}: #{e.message}"
+   end
+   ```
+
+### Phase 3: API/External Service Calls
+
+**Focus areas:**
+- YouTube API calls
+- OpenAI API calls
+- AWS S3 operations
+- File system operations
+
+**What to check:**
+
+1. **API call logging:**
+   ```ruby
+   # ❌ BAD: No visibility into what's happening
+   def update_video(video_id, title)
+     youtube_service.update_video(video_id, title: title)
+   end
+
+   # ✅ GOOD: Log request and response
+   def update_video(video_id, title)
+     log.debug("YouTube API: Updating video #{video_id}")
+     log.debug("New title: #{title}")
+
+     response = youtube_service.update_video(video_id, title: title)
+
+     log.debug("YouTube API: Update successful")
+     log.debug("Response: #{response.inspect}")
+     response
+   rescue Google::Apis::ClientError => e
+     log.error("YouTube API error updating video #{video_id}")
+     log.error("Error code: #{e.status_code}")
+     log.error("Error message: #{e.message}")
+     log.error("Title attempted: #{title}")
+     raise
+   end
+   ```
+
+2. **Retry logic logging:**
+   ```ruby
+   # ✅ GOOD: Log retry attempts
+   def api_call_with_retry(max_retries: 3)
+     retries = 0
+     begin
+       log.debug("API call attempt #{retries + 1}/#{max_retries}")
+       yield
+     rescue TransientError => e
+       retries += 1
+       if retries < max_retries
+         wait_time = 2 ** retries
+         log.warn("API call failed, retrying in #{wait_time}s (attempt #{retries}/#{max_retries})")
+         log.warn("Error: #{e.message}")
+         sleep wait_time
+         retry
+       else
+         log.error("API call failed after #{max_retries} attempts")
+         log.error("Final error: #{e.message}")
+         raise
+       end
+     end
+   end
+   ```
+
+### Phase 4: Type Coercion/Validation
+
+**Focus areas:**
+- Input validation in CLI commands
+- Type conversion (string to int, etc.)
+- Hash/array access with potential nil values
+
+**What to check:**
+
+1. **Type validation:**
+   ```ruby
+   # ❌ BAD: Assumes type is correct
+   def process_limit(limit)
+     (0...limit).each { |i| process_item(i) }
+   end
+
+   # ✅ GOOD: Validate and convert with logging
+   def process_limit(limit)
+     log.debug("Processing limit: #{limit.inspect} (#{limit.class})")
+
+     unless limit.respond_to?(:to_i)
+       log.error("Invalid limit type: #{limit.class}")
+       log.error("Expected: Integer or String, got: #{limit.inspect}")
+       raise ArgumentError, "Limit must be numeric, got: #{limit.class}"
+     end
+
+     limit_int = limit.to_i
+     if limit_int <= 0
+       log.warn("Non-positive limit: #{limit_int}, defaulting to 10")
+       limit_int = 10
+     end
+
+     log.debug("Processing #{limit_int} items")
+     (0...limit_int).each { |i| process_item(i) }
+   end
+   ```
+
+2. **Hash access safety:**
+   ```ruby
+   # ❌ BAD: Will blow up if key missing
+   def get_channel_name(channel_data)
+     channel_data['name'].upcase
+   end
+
+   # ✅ GOOD: Safe access with logging
+   def get_channel_name(channel_data)
+     log.debug("Extracting channel name from: #{channel_data.keys.join(', ')}")
+
+     name = channel_data['name']
+     if name.nil?
+       log.error("Missing 'name' key in channel data")
+       log.error("Available keys: #{channel_data.keys.join(', ')}")
+       log.error("Channel data: #{channel_data.inspect}")
+       raise DataError, "Channel data missing 'name' field"
+     end
+
+     log.debug("Channel name: #{name}")
+     name.upcase
+   end
+   ```
+
+### Phase 5: Environment-Triggered Logging
+
+**What to check:**
+
+1. **Debug flag support:**
+   ```ruby
+   # ✅ GOOD: Support for DEBUG environment variable
+   class Logger
+     def self.debug?
+       ENV['DEBUG'] == 'true' || ENV['DAM_DEBUG'] == 'true'
+     end
+
+     def debug(message)
+       return unless self.class.debug?
+       puts "[DEBUG] #{Time.now.strftime('%H:%M:%S')} #{message}"
+     end
+
+     def info(message)
+       puts "[INFO] #{message}"
+     end
+
+     def warn(message)
+       warn "[WARN] #{message}"
+     end
+
+     def error(message)
+       warn "[ERROR] #{message}"
+     end
+   end
+   ```
+
+2. **Usage instructions:**
+   ```bash
+   # Normal operation (quiet)
+   dam list appydave
+
+   # Debug mode (verbose)
+   DEBUG=true dam list appydave
+   DAM_DEBUG=true dam list appydave
+
+   # Debug mode for specific command
+   DEBUG=true gpt_context -i '**/*.rb' -d
+   ```
+
+3. **Documentation:**
+   ```markdown
+   ## Debugging
+
+   Enable debug logging with environment variables:
+
+   ```bash
+   DEBUG=true dam list appydave
+   DAM_DEBUG=true vat s3-status voz boy-baker
+   ```
+
+   Debug logs show:
+   - Configuration loading and values
+   - Path resolution steps
+   - API request/response details
+   - File operations and validations
+   ```
+
+### Phase 6: Silent Failure Detection
+
+**What to flag:**
+
+1. **Rescue without logging:**
+   ```ruby
+   # ❌ BAD: Silent failure
+   def safe_operation
+     risky_operation
+   rescue => e
+     nil
+   end
+
+   # ✅ GOOD: Logged failure
+   def safe_operation
+     risky_operation
+   rescue => e
+     log.error("Operation failed: #{e.class}")
+     log.error("Error message: #{e.message}")
+     log.error("Backtrace: #{e.backtrace.first(5).join("\n")}")
+     nil
+   end
+   ```
+
+2. **Empty rescue blocks:**
+   ```ruby
+   # ❌ BAD: Swallows all errors
+   begin
+     operation
+   rescue
+   end
+
+   # ✅ GOOD: At minimum, log it
+   begin
+     operation
+   rescue => e
+     log.warn("Operation failed but continuing: #{e.message}")
+   end
+   ```
+
+3. **Unhelpful error messages:**
+   ```ruby
+   # ❌ BAD: Generic error
+   raise "Invalid input"
+
+   # ✅ GOOD: Specific error with context
+   raise ArgumentError, "Invalid brand name: #{brand}. Expected one of: #{VALID_BRANDS.join(', ')}"
+   ```
+
+## Report Format
+
+```markdown
+# Defensive Logging Audit - [Date]
+
+## Summary
+- **Files analyzed:** X Ruby files in lib/
+- **Critical gaps:** Y locations missing nil guards
+- **Silent failures:** Z rescue blocks without logging
+- **Good patterns found:** N files with proper logging
+
+## Critical Gaps 🔴
+
+### 1. Configuration Loading - Missing Nil Guards
+**Location:** `lib/appydave/tools/configuration/settings.rb:45`
+
+**Current code:**
+```ruby
+def video_projects_root
+  config['video-projects-root']
+end
+```
+
+**Problem:**
+- Returns nil if key missing
+- Downstream code will fail with opaque "undefined method for nil:NilClass"
+- No indication of what configuration is missing
+
+**Recommended fix:**
+```ruby
+def video_projects_root
+  value = config['video-projects-root']
+  if value.nil?
+    log.error("Missing 'video-projects-root' in settings.json")
+    log.error("Config file: #{config_path}")
+    log.error("Available keys: #{config.keys.join(', ')}")
+    raise ConfigurationError, "Missing required setting 'video-projects-root'. Run 'ad_config -e' to configure."
+  end
+  log.debug("video-projects-root: #{value}")
+  value
+end
+```
+
+**Impact:** High - This is the "Jan Problem" - remote users can't debug config issues
+
+---
+
+### 2. Silent API Failures
+**Location:** `lib/appydave/tools/youtube_manager/client.rb:89`
+
+**Current code:**
+```ruby
+def update_video(video_id, title)
+  youtube_service.update_video(video_id, title: title)
+rescue => e
+  nil
+end
+```
+
+**Problem:**
+- API failures are silent
+- No logging of what went wrong
+- Returns nil without explanation
+
+**Recommended fix:**
+```ruby
+def update_video(video_id, title)
+  log.debug("YouTube API: Updating video #{video_id}")
+  log.debug("New title: #{title}")
+
+  result = youtube_service.update_video(video_id, title: title)
+  log.debug("Update successful")
+  result
+rescue Google::Apis::ClientError => e
+  log.error("YouTube API error: #{e.status_code}")
+  log.error("Message: #{e.message}")
+  log.error("Video ID: #{video_id}")
+  log.error("Title: #{title}")
+  raise
+end
+```
+
+**Impact:** High - API failures are hard to diagnose
+
+---
+
+## Moderate Gaps 🟡
+
+### 1. Path Validation Missing
+**Locations:**
+- `lib/appydave/tools/dam/project_resolver.rb:34`
+- `lib/appydave/tools/dam/commands/list.rb:56`
+
+**Issue:** Path construction doesn't validate that directories exist
+
+**Recommendation:**
+```ruby
+def validate_path(path, description)
+  log.debug("Validating #{description}: #{path}")
+
+  unless File.exist?(path)
+    log.error("#{description} not found: #{path}")
+    log.error("Parent exists: #{File.directory?(File.dirname(path))}")
+    raise PathError, "#{description} does not exist: #{path}"
+  end
+
+  log.debug("#{description} validated")
+  path
+end
+```
+
+---
+
+### 2. No Debug Mode Support
+**Issue:** No consistent way to enable debug logging
+
+**Recommendation:**
+1. Add Logger class with debug flag support
+2. Document DEBUG=true usage
+3. Add to all CLI commands
+
+---
+
+## Good Patterns Found ✅
+
+### 1. Configuration Echo in DAM
+**Location:** `lib/appydave/tools/dam/configuration.rb:23-30`
+
+**Code:**
+```ruby
+def log_configuration
+  return unless debug?
+  puts "=== DAM Configuration ==="
+  puts "Video projects root: #{video_projects_root}"
+  puts "Current directory: #{Dir.pwd}"
+  puts "========================="
+end
+```
+
+**Why it's good:** Helps users verify configuration is loaded correctly
+
+**Recommend:** Apply this pattern to all configuration loading
+
+---
+
+### 2. Detailed S3 Error Logging
+**Location:** `lib/appydave/tools/dam/s3_sync.rb:78-85`
+
+**Why it's good:** S3 errors include bucket, key, and AWS error details
+
+**Recommend:** Apply this pattern to all external service calls
+
+---
+
+## Implementation Priority
+
+### Phase 1: Critical Configuration Issues (Do Now)
+1. [ ] Add nil guards to all configuration value access
+2. [ ] Add configuration echo on CLI startup (when DEBUG=true)
+3. [ ] Add helpful error messages for missing config values
+
+**Files to update:**
+- `lib/appydave/tools/configuration/settings.rb`
+- `lib/appydave/tools/configuration/channels.rb`
+- `lib/appydave/tools/dam/configuration.rb`
+
+**Estimated effort:** 2-3 hours
+
+---
+
+### Phase 2: Path Resolution Safety (Do Soon)
+1. [ ] Add logging to brand resolution
+2. [ ] Add path validation with existence checks
+3. [ ] Add detailed error messages for path failures
+
+**Files to update:**
+- `lib/appydave/tools/dam/project_resolver.rb`
+- `lib/appydave/tools/dam/brand_resolver.rb`
+
+**Estimated effort:** 1-2 hours
+
+---
+
+### Phase 3: API Call Logging (Do When Touching API Code)
+1. [ ] Add request/response logging to YouTube API
+2. [ ] Add retry logging
+3. [ ] Add error context to API failures
+
+**Files to update:**
+- `lib/appydave/tools/youtube_manager/client.rb`
+- `lib/appydave/tools/cli_actions/youtube_*.rb`
+
+**Estimated effort:** 1-2 hours
+
+---
+
+### Phase 4: Debug Mode Infrastructure (Nice to Have)
+1. [ ] Create consistent Logger class
+2. [ ] Add DEBUG environment variable support
+3. [ ] Document debug mode in README
+
+**New files:**
+- `lib/appydave/tools/utils/logger.rb`
+
+**Estimated effort:** 1 hour
+
+---
+
+## Testing Recommendations
+
+### Manual Testing Checklist
+```bash
+# Test missing configuration
+rm ~/.config/appydave/settings.json
+dam list appydave
+# Expected: Clear error message about missing settings.json
+
+# Test missing configuration value
+echo '{}' > ~/.config/appydave/settings.json
+dam list appydave
+# Expected: Clear error message about missing video-projects-root
+
+# Test debug mode
+DEBUG=true dam list appydave
+# Expected: Verbose logging of configuration loading, path resolution
+
+# Test invalid brand
+dam list invalid-brand
+# Expected: Error message listing valid brands
+
+# Test missing project directory
+echo '{"video-projects-root": "/tmp/does-not-exist"}' > ~/.config/appydave/settings.json
+dam list appydave
+# Expected: Clear error about directory not existing
+```
+
+### Automated Testing
+Add specs that verify error messages:
+
+```ruby
+RSpec.describe Configuration do
+  context 'when configuration is missing' do
+    it 'raises helpful error' do
+      allow(File).to receive(:exist?).and_return(false)
+
+      expect { config.video_projects_root }.to raise_error(
+        ConfigurationError,
+        /Missing required setting 'video-projects-root'/
+      )
+    end
+  end
+end
+```
+
+---
+
+## Logging Standards for This Project
+
+### Log Levels
+- **debug:** Detailed flow information (config values, paths, API requests)
+- **info:** High-level operations (command started, operation completed)
+- **warn:** Recoverable issues (using defaults, retrying operations)
+- **error:** Failures that prevent operation (missing config, API errors)
+
+### Log Format
+```ruby
+log.debug("#{self.class.name}##{__method__}: #{message}")
+log.error("ERROR in #{self.class.name}##{__method__}: #{message}")
+```
+
+### What to Log
+✅ **Always log:**
+- Configuration loading (in debug mode)
+- Configuration value access (in debug mode)
+- Path construction and validation (in debug mode)
+- External API calls (request and response)
+- File operations (read, write, delete)
+- Error conditions (always, not just debug mode)
+
+❌ **Don't log:**
+- Secrets (API keys, tokens, passwords)
+- User personal data (unless absolutely necessary for debugging)
+- Inside tight loops (will spam logs)
+
+### Debug Mode Usage
+```ruby
+# Enable via environment variable
+DEBUG=true dam list appydave
+
+# Or project-specific flag
+DAM_DEBUG=true dam s3-status voz boy-baker
+```
+
+---
+
+## Example: Before and After
+
+### Before (Current Code)
+```ruby
+def project_path
+  root = config['video-projects-root']
+  brand = brand_folder
+  File.join(root, brand, project_name)
+end
+```
+
+**Problems:**
+- No logging of what's happening
+- If `root` is nil, error is "undefined method `join' for nil:NilClass" (useless)
+- If `brand` is nil, error is equally useless
+- No way to debug where the nil came from
+
+### After (With Defensive Logging)
+```ruby
+def project_path
+  log.debug("#{self.class}#project_path called")
+  log.debug("  project_name: #{project_name}")
+
+  root = config['video-projects-root']
+  if root.nil?
+    log.error("Configuration missing: video-projects-root")
+    log.error("  Config file: #{config_path}")
+    log.error("  Available keys: #{config.keys.join(', ')}")
+    raise ConfigurationError, "Missing 'video-projects-root' in settings.json. Run 'ad_config -e' to set."
+  end
+  log.debug("  video-projects-root: #{root}")
+
+  brand = brand_folder
+  if brand.nil?
+    log.error("Brand resolution failed for: #{@brand_name}")
+    log.error("  Available brands: #{BrandResolver::BRAND_MAP.keys.join(', ')}")
+    raise BrandError, "Could not resolve brand: #{@brand_name}"
+  end
+  log.debug("  brand_folder: #{brand}")
+
+  path = File.join(root, brand, project_name)
+  log.debug("  final path: #{path}")
+
+  unless File.directory?(path)
+    log.warn("Project directory does not exist: #{path}")
+    log.warn("  This may be a new project or misconfigured path")
+  end
+
+  path
+end
+```
+
+**Benefits:**
+- Every step is logged (in debug mode)
+- Nil values are caught with context
+- Error messages tell you exactly what's missing
+- User gets actionable instructions ("Run 'ad_config -e'")
+- Remote debugging is actually possible
+
+---
+
+## Notes for AI Assistants
+
+- **This is a safety audit, not a refactoring** - Focus on finding gaps, not rewriting code
+- **Nil errors are the enemy** - Every place that could return nil should be logged
+- **Configuration is critical** - This is the #1 source of remote debugging pain
+- **Be specific** - Show exact file locations and code snippets
+- **Provide fixes** - Don't just identify problems, show how to fix them
+- **Consider the user** - Error messages should help users fix their config, not just report failures
+- **Debug mode is key** - Users should be able to turn on verbose logging when needed
+- **Don't break existing code** - Additions only, don't change working logic
+
+---
+
+**Last updated:** 2025-01-21