appydave-tools 0.66.0 → 0.68.0

data/docs/code-quality/uat-plan-2025-01-22.md

@@ -0,0 +1,374 @@
+# User Acceptance Test Plan - DAM CLI Enhancements
+
+**Test Date:** 2025-01-22
+**Commit Range:** `9e49668` → `4228b51` (75 commits)
+**Test Scope:** Verify core functionality intact + new features working
+
+---
+
+## Delivery Method
+
+This test plan will be executed **interactively** using the following process:
+
+1. **AI announces:** "Testing [feature]: [description]"
+2. **AI runs:** `command here`
+3. **AI shows:** Output from command
+4. **User responds:**
+   - Type `1` to proceed to next test (affirmative)
+   - OR provide feedback/change of plan
+
+**Important:**
+- Tests are executed **one at a time** (not batched)
+- Quick verification focus (not exhaustive testing)
+- S3 operations use `--dry-run` flag (no actual uploads/downloads)
+- User can interrupt at any point with feedback
+
+---
+
+## Test Structure
+
+### Suite 1: Core Functionality (Baseline)
+**Goal:** Verify nothing broke from original functionality
+
+**Tests:**
+1. Brand listing (default view)
+2. Brand listing (invalid brand with error)
+3. Project listing (specific brand)
+4. Project listing (pattern matching)
+5. S3 status check
+6. Git status check
+
+### Suite 2: New Features (Additions)
+**Goal:** Verify new capabilities work as intended
+
+**Tests:**
+7. Brand listing (--detailed flag)
+8. Project listing (--detailed flag)
+9. Fuzzy matching (typo suggestions)
+10. Git status column (brand level)
+11. Git status column (project level)
+12. S3 sync status (3-state model)
+13. S3 timestamps (detailed view)
+
+### Suite 3: Edge Cases (Regressions)
+**Goal:** Catch potential issues from refactoring
+
+**Tests:**
+14. Case-insensitive brand resolution
+15. Brand shortcuts (ad, voz, joy, ss)
+16. S3 operations with no staging folder
+17. Git operations on non-git directories
+
+### Suite 4: Performance Check
+**Goal:** Ensure no major slowdowns
+
+**Tests:**
+18. List all brands (measure response time)
+19. List brand projects with many items
+20. Detailed view performance
+
+---
+
+## Test Execution Plan
+
+---
+
+### **SUITE 1: CORE FUNCTIONALITY (BASELINE)**
+
+#### Test 1: Brand Listing (Default View)
+**Purpose:** Verify default brand list still works
+**Command:** `dam list`
+**Expected:**
+- Shows all brands
+- Displays: BRAND, KEY, PROJECTS, SIZE, LAST MODIFIED, GIT, S3 SYNC columns
+- No errors
+
+---
+
+#### Test 2: Invalid Brand (Error Handling)
+**Purpose:** Verify error messages work
+**Command:** `dam list invalidbrand`
+**Expected:**
+- Error message: "Brand directory not found: invalidbrand"
+- Shows available brands
+- No crash
+
+---
+
+#### Test 3: Project Listing (Specific Brand)
+**Purpose:** Verify project listing unchanged
+**Command:** `dam list appydave`
+**Expected:**
+- Shows all appydave projects
+- Displays project names, sizes, dates
+- No errors
+
+---
+
+#### Test 4: Pattern Matching
+**Purpose:** Verify pattern expansion works
+**Command:** `dam list appydave 'b6*'`
+**Expected:**
+- Shows only projects matching b6* (b60-b69)
+- Pattern correctly expands
+- No errors
+
+---
+
+#### Test 5: S3 Status Check
+**Purpose:** Verify S3 status command works
+**Command:** `dam s3-status appydave b65`
+**Expected:**
+- Shows S3 sync status for b65
+- Lists files in S3 vs local
+- Displays sync state (upload/download/synced)
+- No errors
+
+---
+
+#### Test 6: Git Status Check
+**Purpose:** Verify git status detection works
+**Command:** `dam status appydave`
+**Expected:**
+- Shows git repository status
+- Shows branch, commits ahead/behind
+- Shows modified/untracked files
+- No errors
+
+---
+
+### **SUITE 2: NEW FEATURES (ADDITIONS)**
+
+#### Test 7: Brand Listing (--detailed Flag)
+**Purpose:** Verify new --detailed flag for brands
+**Command:** `dam list --detailed`
+**Expected:**
+- Shows extended columns: PATH, SSD BACKUP, WORKFLOW, ACTIVE PROJECTS
+- Table width approximately 200 characters
+- All data populated correctly
+- No errors
+
+---
+
+#### Test 8: Project Listing (--detailed Flag)
+**Purpose:** Verify new --detailed flag for projects
+**Command:** `dam list appydave --detailed`
+**Expected:**
+- Shows extended columns: HEAVY/LIGHT FILES, SSD BACKUP, S3 TIMESTAMPS
+- Additional metadata displayed
+- No errors
+
+---
+
+#### Test 9: Fuzzy Matching (Typo Suggestions)
+**Purpose:** Verify "Did you mean?" feature
+**Command:** `dam list appydav`
+**Expected:**
+- Error message shows "Did you mean?"
+- Suggests "appydave"
+- Helpful error format
+- No crash
+
+---
+
+#### Test 10: Git Status Column (Brand Level)
+**Purpose:** Verify GIT STATUS column in brand list
+**Command:** `dam list`
+**Expected:**
+- Shows "✓ clean" or "⚠️ changes" for each brand
+- Accurate reflection of git state
+- No errors
+
+---
+
+#### Test 11: Git Status Column (Project Level)
+**Purpose:** Verify GIT column in project list
+**Command:** `dam list appydave`
+**Expected:**
+- Shows git status per project (if git repo)
+- Shows "N/A" for non-git projects
+- No errors
+
+---
+
+#### Test 12: S3 Sync Status (3-State Model)
+**Purpose:** Verify ↑ upload / ↓ download / ✓ synced states
+**Command:** `dam list appydave`
+**Expected:**
+- S3 SYNC column shows one of: ↑ upload, ↓ download, ✓ synced, none, N/A
+- Accurate reflection of sync state
+- No errors
+
+---
+
+#### Test 13: S3 Timestamps (Detailed View)
+**Purpose:** Verify last upload/download times
+**Command:** `dam list appydave --detailed`
+**Expected:**
+- Shows S3 LAST UPLOAD and LAST DOWNLOAD columns
+- Timestamps formatted correctly
+- Shows "N/A" if no S3 configured
+- No errors
+
+---
+
+### **SUITE 3: EDGE CASES (REGRESSIONS)**
+
+#### Test 14: Case-Insensitive Brand Resolution
+**Purpose:** Verify case handling works
+**Commands:**
+- `dam list appydave`
+- `dam list APPYDAVE`
+- `dam list AppyDave`
+
+**Expected:**
+- All three commands work identically
+- Same projects listed
+- No errors
+
+---
+
+#### Test 15: Brand Shortcuts
+**Purpose:** Verify shortcuts resolve correctly
+**Commands:**
+- `dam list ad` (should resolve to appydave)
+- `dam list voz` (should resolve to voz)
+- `dam list joy` (should resolve to beauty-and-joy)
+- `dam list ss` (should resolve to supportsignal)
+
+**Expected:**
+- Each shortcut resolves to correct brand
+- Projects listed correctly
+- No errors
+
+---
+
+#### Test 16: S3 Operations (No Staging Folder)
+**Purpose:** Verify graceful handling when s3-staging/ doesn't exist
+**Command:** `dam s3-up appydave b40 --dry-run`
+**Expected:**
+- Clear error message OR creates staging directory
+- No crash
+- Helpful guidance
+
+---
+
+#### Test 17: Git Operations (Non-Git Directory)
+**Purpose:** Verify graceful handling of non-git projects
+**Command:** `dam list appydave` (view projects with no .git)
+**Expected:**
+- GIT column shows "N/A" for non-git projects
+- No errors
+- No crash
+
+---
+
+### **SUITE 4: PERFORMANCE CHECK**
+
+#### Test 18: List All Brands (Response Time)
+**Purpose:** Ensure no major slowdown from new features
+**Command:** `time dam list`
+**Expected:**
+- Completes in < 3 seconds (reasonable for filesystem scan)
+- Output matches expected format
+- No errors
+
+**Baseline:** Original implementation time (if known)
+
+---
+
+#### Test 19: List Brand Projects (Many Items)
+**Purpose:** Verify performance with 20+ projects
+**Command:** `time dam list appydave`
+**Expected:**
+- Completes in < 5 seconds
+- All projects displayed
+- No errors
+
+---
+
+#### Test 20: Detailed View Performance
+**Purpose:** Ensure --detailed flag doesn't cause excessive slowdown
+**Command:** `time dam list appydave --detailed`
+**Expected:**
+- Completes in < 10 seconds (allows for S3 API calls)
+- All data populated
+- No errors
+
+**Note:** This may be slower due to S3 API calls per project
+
+---
+
+## Success Criteria
+
+### Must Pass (Critical)
+- ✅ All baseline tests (Suite 1) pass
+- ✅ No breaking changes to existing commands
+- ✅ No crashes or unhandled exceptions
+- ✅ Error messages are helpful
+
+### Should Pass (Important)
+- ✅ All new features work as designed (Suite 2)
+- ✅ Edge cases handled gracefully (Suite 3)
+- ✅ Performance acceptable (Suite 4)
+
+### Nice to Have (Enhancements)
+- ✅ Fuzzy matching suggestions accurate
+- ✅ Git/S3 status columns informative
+- ✅ Detailed views show useful metadata
+
+---
+
+## Failure Handling
+
+If a test fails:
+1. **Document the failure:**
+   - Test number
+   - Command run
+   - Expected vs actual output
+   - Error message (if any)
+
+2. **Classify severity:**
+   - 🔴 **CRITICAL:** Core functionality broken (Suite 1)
+   - 🟡 **MODERATE:** New feature not working (Suite 2)
+   - 🟢 **MINOR:** Edge case or performance issue (Suite 3/4)
+
+3. **Decision:**
+   - Critical failures → Stop testing, fix immediately
+   - Moderate failures → Document, continue testing
+   - Minor failures → Note for future improvement
+
+---
+
+## Test Execution Checklist
+
+Before starting:
+- [ ] Working directory: `/Users/davidcruwys/dev/ad/appydave-tools`
+- [ ] Dam command available: `which dam` or `bin/dam`
+- [ ] Configuration valid: `ad_config -l`
+- [ ] Test brands exist: appydave, voz, etc.
+
+During testing:
+- [ ] Execute tests one at a time
+- [ ] Wait for user "1" confirmation before proceeding
+- [ ] Document any unexpected output
+- [ ] Note performance anomalies
+
+After testing:
+- [ ] Summarize results (pass/fail counts)
+- [ ] Document any critical issues
+- [ ] Provide recommendations
+
+---
+
+## Notes
+
+- **S3 Testing:** Uses `--dry-run` flag to avoid actual uploads/downloads
+- **Git Testing:** Read-only operations, no repository modifications
+- **Performance:** Measured with `time` command, baseline comparison if available
+- **Interactive Format:** User controls pace with "1" confirmations
+
+---
+
+**Test plan prepared:** 2025-01-22
+**Ready to execute:** Awaiting user confirmation to begin Suite 1

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

@@ -91,8 +91,14 @@ module Appydave
             end
 
             unless Dir.exist?(brand_path)
+              # Get available brands for error message
               available = Config.available_brands_display
-              raise BrandNotFoundError.new(brand, available)
+
+              # Use fuzzy matching to suggest similar brands
+              available_list = Config.available_brands
+              suggestions = FuzzyMatcher.find_matches(brand, available_list, threshold: 3)
+
+              raise BrandNotFoundError.new(brand, available, suggestions)
             end
 
             key

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

@@ -8,8 +8,16 @@ module Appydave
 
       # Raised when brand directory not found
       class BrandNotFoundError < DamError
-        def initialize(brand, available_brands = nil)
+        def initialize(brand, available_brands = nil, suggestions = nil)
           message = "Brand directory not found: #{brand}"
+
+          # Add fuzzy match suggestions if provided
+          if suggestions && !suggestions.empty?
+            message += "\n\nDid you mean?"
+            suggestions.each { |s| message += "\n  - #{s}" }
+          end
+
+          # Add full list of available brands
           message += "\n\nAvailable brands:\n#{available_brands}" if available_brands && !available_brands.empty?
           super(message)
         end

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

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module Appydave
+  module Tools
+    module Dam
+      # Fuzzy matching for brand names using Levenshtein distance
+      class FuzzyMatcher
+        class << self
+          # Find closest matches to input string
+          # @param input [String] Input string to match
+          # @param candidates [Array<String>] List of valid options
+          # @param threshold [Integer] Maximum distance to consider a match (default: 3)
+          # @return [Array<String>] Sorted list of closest matches
+          def find_matches(input, candidates, threshold: 3)
+            return [] if input.nil? || input.empty? || candidates.empty?
+
+            # Calculate distances and filter by threshold
+            matches = candidates.map do |candidate|
+              distance = levenshtein_distance(input.downcase, candidate.downcase)
+              { candidate: candidate, distance: distance }
+            end
+
+            # Filter by threshold
+            matches = matches.select { |m| m[:distance] <= threshold }
+
+            # Sort by distance (closest first)
+            matches.sort_by { |m| m[:distance] }.map { |m| m[:candidate] }
+          end
+
+          # Calculate Levenshtein distance between two strings
+          # @param str1 [String] First string
+          # @param str2 [String] Second string
+          # @return [Integer] Edit distance
+          def levenshtein_distance(str1, str2)
+            return str2.length if str1.empty?
+            return str1.length if str2.empty?
+
+            # Create distance matrix
+            matrix = Array.new(str1.length + 1) { Array.new(str2.length + 1) }
+
+            # Initialize first row and column
+            (0..str1.length).each { |i| matrix[i][0] = i }
+            (0..str2.length).each { |j| matrix[0][j] = j }
+
+            # Calculate distances
+            (1..str1.length).each do |i|
+              (1..str2.length).each do |j|
+                cost = str1[i - 1] == str2[j - 1] ? 0 : 1
+                matrix[i][j] = [
+                  matrix[i - 1][j] + 1,      # deletion
+                  matrix[i][j - 1] + 1,      # insertion
+                  matrix[i - 1][j - 1] + cost # substitution
+                ].min
+              end
+            end
+
+            matrix[str1.length][str2.length]
+          end
+        end
+      end
+    end
+  end
+end