appydave-tools 0.74.0 → 0.74.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 44ca2e425677ffd01f35cbad749a7cf026321e30e8133b2db75b08d3062407e6
-  data.tar.gz: e6555b956b2d404689761382faecf83458eefdb9453fbdfbc7fdb1406f37b585
+  metadata.gz: ef8315540ea80d07de1a6eba6733c1be84e21caaa4251dbb60e9a2207abf9758
+  data.tar.gz: 3a386ab9c8b399ceca1056f20fae6543bc534ddf37a7d104363acc09ad694e48
 SHA512:
-  metadata.gz: 88a430612add3c650c890797874ad17332bbd8c4507bfa2e847e310cbec6b659f719fdfa7db47f2a672e22080ad070cc026fb1fbf66b028b740babac7261502a
-  data.tar.gz: ab498bebd3971c75d7bc222af0c1c5405568c78e2d6fbec47a9d64818f78df8504c720cbd8c25a3ac48356e2e7ba586520f345074d157799d974e789b8a48c8b
+  metadata.gz: 70af1beaa0539e9a71ffb1e4435ffe1afad1da73cfbbe4f16c780110684975fdbf3de5602e7cc5b9bd226404158d0f24aee5126186b3821235b782508bc9150b
+  data.tar.gz: 6e06cc27ccebd7d49ba9831f3e9f1345f96bc0ffce681fc56be6a08799a32d828b8c68e32633d74a99b397a1a7bde699c89a5077745439ccbc9f3c8cf3e2af2e

data/CHANGELOG.md

@@ -1,3 +1,10 @@
+# [0.74.0](https://github.com/appydave/appydave-tools/compare/v0.73.0...v0.74.0) (2025-12-18)
+
+
+### Features
+
+* add auto-regenerate aliases after jump CRUD operations ([0fe21d7](https://github.com/appydave/appydave-tools/commit/0fe21d72c4af492ebebf75645683dd49b9a2fe52))
+
 # [0.73.0](https://github.com/appydave/appydave-tools/compare/v0.72.0...v0.73.0) (2025-12-18)
 
 

data/bin/dam

@@ -35,7 +35,7 @@ class VatCLI
     }
   end
 
-  # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
+  # rubocop:disable Metrics/MethodLength
   def run
     command, *args = ARGV
 
@@ -78,12 +78,12 @@ class VatCLI
       exit 1
     end
   end
-  # rubocop:enable Metrics/AbcSize, Metrics/MethodLength
+  # rubocop:enable Metrics/MethodLength
 
   private
 
   # Show help information
-  # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength
+  # rubocop:disable Metrics/CyclomaticComplexity, Metrics/MethodLength
   def help_command(args)
     topic = args[0]
 
@@ -126,7 +126,7 @@ class VatCLI
       puts "Run 'dam help' for general help."
     end
   end
-  # rubocop:enable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength
+  # rubocop:enable Metrics/CyclomaticComplexity, Metrics/MethodLength
 
   # List brands and projects
   def list_command(args)
@@ -463,7 +463,7 @@ class VatCLI
   end
 
   # Parse S3 command arguments
-  # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
+  # rubocop:disable Metrics/MethodLength
   def parse_s3_args(args, command)
     dry_run = args.include?('--dry-run')
     force = args.include?('--force')
@@ -508,7 +508,7 @@ class VatCLI
 
     { brand: brand_key, project: project_id, dry_run: dry_run, force: force }
   end
-  # rubocop:enable Metrics/AbcSize, Metrics/MethodLength
+  # rubocop:enable Metrics/MethodLength
 
   def valid_brand?(brand_key)
     Appydave::Tools::Configuration::Config.configure
@@ -520,7 +520,7 @@ class VatCLI
   # Mutates the matched_projects hash to add :local_status key
   # @param matched_projects [Hash] Map of project_id => S3 data
   # @param brand_key [String] Brand key (e.g., 'appydave', 'ss')
-  # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
+  # rubocop:disable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
   def add_local_sync_status!(matched_projects, brand_key)
     matched_projects.each do |project_id, data|
       project_path = Appydave::Tools::Dam::Config.project_path(brand_key, project_id)
@@ -551,7 +551,7 @@ class VatCLI
       end
     end
   end
-  # rubocop:enable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
+  # rubocop:enable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
 
   # Format local sync status for display
   # @param status [Symbol] :synced, :no_files, :partial, :no_project
@@ -660,7 +660,7 @@ class VatCLI
     true
   end
 
-  # rubocop:disable Metrics/MethodLength, Metrics/AbcSize
+  # rubocop:disable Metrics/MethodLength
   def display_s3_files(files, brand_key, project_id, shareable)
     brand_display = Appydave::Tools::Dam::Config.expand_brand(brand_key)
 
@@ -721,7 +721,7 @@ class VatCLI
 
     puts ''
   end
-  # rubocop:enable Metrics/MethodLength, Metrics/AbcSize
+  # rubocop:enable Metrics/MethodLength
 
   # Help text methods
   # rubocop:disable Metrics/MethodLength
@@ -1402,7 +1402,7 @@ class VatCLI
     exit 1
   end
 
-  # rubocop:disable Metrics/MethodLength, Metrics/CyclomaticComplexity, Metrics/AbcSize
+  # rubocop:disable Metrics/MethodLength, Metrics/CyclomaticComplexity
   def scan_single_brand_s3(brand_arg)
     puts "🔄 Scanning S3 for #{brand_arg}..."
     puts ''
@@ -1495,10 +1495,10 @@ class VatCLI
     puts "   • Manifest: #{manifest_path}"
     puts ''
   end
-  # rubocop:enable Metrics/MethodLength, Metrics/CyclomaticComplexity, Metrics/AbcSize
+  # rubocop:enable Metrics/MethodLength, Metrics/CyclomaticComplexity
 
   # Display S3 scan results in table format
-  # rubocop:disable Metrics/MethodLength, Metrics/AbcSize, Metrics/CyclomaticComplexity, Style/FormatStringToken
+  # rubocop:disable Metrics/MethodLength, Metrics/CyclomaticComplexity, Style/FormatStringToken
   def display_s3_scan_table(matched_projects, orphaned_projects, bucket, prefix, region)
     puts '✅ S3 Projects Report'
     puts ''
@@ -1540,9 +1540,9 @@ class VatCLI
       puts "     #{console_url}"
     end
   end
-  # rubocop:enable Metrics/MethodLength, Metrics/AbcSize, Metrics/CyclomaticComplexity, Style/FormatStringToken
+  # rubocop:enable Metrics/MethodLength, Metrics/CyclomaticComplexity, Style/FormatStringToken
 
-  # rubocop:disable Metrics/MethodLength, Metrics/AbcSize
+  # rubocop:disable Metrics/MethodLength
   def scan_all_brands_s3
     Appydave::Tools::Configuration::Config.configure
     brands_config = Appydave::Tools::Configuration::Config.brands
@@ -1583,7 +1583,7 @@ class VatCLI
     puts ''
     puts "Total brands scanned: #{successful.size}/#{results.size}"
   end
-  # rubocop:enable Metrics/MethodLength, Metrics/AbcSize
+  # rubocop:enable Metrics/MethodLength
 
   # Format bytes in human-readable format
   # rubocop:disable Style/FormatStringToken

data/bin/zsh_history.rb

@@ -20,7 +20,6 @@ class ZshHistoryCLI
     }
   end
 
-  # rubocop:disable Metrics/MethodLength, Metrics/AbcSize
   def run
     command = ARGV[0]
 
@@ -65,7 +64,6 @@ class ZshHistoryCLI
       exit 1
     end
   end
-  # rubocop:enable Metrics/MethodLength, Metrics/AbcSize
 
   private
 
@@ -73,7 +71,7 @@ class ZshHistoryCLI
   # HELP COMMAND
   # ============================================================
 
-  # rubocop:disable Metrics/MethodLength, Metrics/CyclomaticComplexity
+  # rubocop:disable Metrics/CyclomaticComplexity
   def help_command(args)
     topic = args[0]
 
@@ -110,9 +108,8 @@ class ZshHistoryCLI
       puts '  zsh_history help workflow   # Typical usage workflow'
     end
   end
-  # rubocop:enable Metrics/MethodLength, Metrics/CyclomaticComplexity
+  # rubocop:enable Metrics/CyclomaticComplexity
 
-  # rubocop:disable Metrics/MethodLength
   def show_main_help
     puts <<~HELP
       ZSH History - Parse, filter, and manage shell history
@@ -493,13 +490,11 @@ class ZshHistoryCLI
         - ^ anchors to start of command
     HELP
   end
-  # rubocop:enable Metrics/MethodLength
 
   # ============================================================
   # SHOW COMMAND
   # ============================================================
 
-  # rubocop:disable Metrics/AbcSize
   def show_command(args)
     options = parse_common_options(args)
 
@@ -526,13 +521,11 @@ class ZshHistoryCLI
 
     write_output(output, options[:output])
   end
-  # rubocop:enable Metrics/AbcSize
 
   # ============================================================
   # PURGE COMMAND
   # ============================================================
 
-  # rubocop:disable Metrics/MethodLength, Metrics/AbcSize
   def purge_command(args)
     options = parse_common_options(args)
 
@@ -568,13 +561,11 @@ class ZshHistoryCLI
       formatter.write_history(commands_to_write, options[:history_path])
     end
   end
-  # rubocop:enable Metrics/MethodLength, Metrics/AbcSize
 
   # ============================================================
   # STATS COMMAND
   # ============================================================
 
-  # rubocop:disable Metrics/AbcSize
   def stats_command(args)
     options = parse_common_options(args)
 
@@ -602,7 +593,6 @@ class ZshHistoryCLI
     formatter = Appydave::Tools::ZshHistory::Formatter.new
     puts formatter.format_stats(result.stats, date_range: date_range)
   end
-  # rubocop:enable Metrics/AbcSize
 
   # ============================================================
   # SEARCH COMMAND
@@ -789,7 +779,6 @@ class ZshHistoryCLI
   # OPTION PARSING
   # ============================================================
 
-  # rubocop:disable Metrics/MethodLength, Metrics/AbcSize
   def parse_common_options(args)
     options = {
       days: nil,
@@ -839,7 +828,6 @@ class ZshHistoryCLI
     parser.parse!(args)
     options
   end
-  # rubocop:enable Metrics/MethodLength, Metrics/AbcSize
 end
 
 # Run CLI

data/docs/architecture/cli/cli-pattern-comparison.md

@@ -2,6 +2,15 @@
 
 Quick reference for choosing the right pattern when creating new CLI tools.
 
+## Overview
+
+AppyDave Tools uses **four CLI patterns**, each optimized for different scales:
+
+- **Pattern 1**: 1 operation - Simple, linear
+- **Pattern 2**: 2-5 commands - Inline routing
+- **Pattern 3**: 6-9 commands - BaseAction (shared validation)
+- **Pattern 4**: 10+ commands - Delegated CLI (testable)
+
 ## Visual Comparison
 
 ```
@@ -68,20 +77,59 @@ Quick reference for choosing the right pattern when creating new CLI tools.
 │                                                                     │
 │  Examples: youtube_manager                                         │
 └─────────────────────────────────────────────────────────────────────┘
+
+┌─────────────────────────────────────────────────────────────────────┐
+│                 PATTERN 4: DELEGATED CLI CLASS                      │
+├─────────────────────────────────────────────────────────────────────┤
+│                                                                     │
+│  bin/tool.rb ──────────────┐                                       │
+│    (30 lines)              │                                        │
+│    cli = CLI.new           │                                        │
+│    exit(cli.run(ARGV))     │                                        │
+│                            │                                        │
+│  lib/tools/tool/ ◄─────────┘                                       │
+│    ├── cli.rb              (Full CLI class - 400+ lines)            │
+│    │   ├── def run(args)   (Entry point with case/when)            │
+│    │   ├── run_search      (Command dispatcher)                    │
+│    │   ├── run_add         (Command dispatcher)                    │
+│    │   └── run_remove      (Command dispatcher)                    │
+│    │                                                                │
+│    ├── search.rb           (Business logic)                        │
+│    ├── crud.rb             (Business logic)                        │
+│    └── config.rb           (Configuration)                         │
+│                                                                     │
+│  spec/tools/tool/                                                   │
+│    ├── cli_spec.rb         (Test CLI behavior!)                    │
+│    ├── search_spec.rb      (Business logic tests)                  │
+│    └── crud_spec.rb        (Business logic tests)                  │
+│                                                                     │
+│  Characteristics:                                                   │
+│  • 10+ commands - Scales excellently                              │
+│  • CLI is testable (RSpec with mocks)                             │
+│  • Dependency injection (config, output, validators)              │
+│  • Exit codes (0-4 for different errors)                          │
+│  • Professional-grade architecture                                │
+│                                                                     │
+│  Example: jump (10 commands, 29-line bin/, 400+ line lib/cli.rb)  │
+└─────────────────────────────────────────────────────────────────────┘
 ```
 
 ## Decision Matrix
 
-| Criteria | Pattern 1 | Pattern 2 | Pattern 3 |
-|----------|-----------|-----------|-----------|
-| **Number of commands** | 1 | 2-5 | 6+ |
-| **Complexity** | Low | Medium | High |
-| **Setup time** | Fast | Medium | Slower |
-| **Scalability** | ❌ | ⚠️ | ✅ |
-| **Consistency enforcement** | N/A | ❌ | ✅ |
-| **Easy to understand** | ✅ | ✅ | ⚠️ |
-| **Shared validation** | N/A | ❌ | ✅ |
-| **Commands share logic** | N/A | ⚠️ | ✅ |
+| Criteria | Pattern 1 | Pattern 2 | Pattern 3 | Pattern 4 |
+|----------|-----------|-----------|-----------|-----------|
+| **Number of commands** | 1 | 2-5 | 6-9 | 10+ |
+| **Complexity** | Low | Medium | High | High |
+| **Setup time** | Fast | Medium | Slower | Slower |
+| **Scalability** | ❌ | ⚠️ | ✅ | ✅✅ |
+| **Testable CLI** | N/A | ❌ | ❌ | ✅ |
+| **Consistency enforcement** | N/A | ❌ | ✅ | ⚠️ |
+| **Easy to understand** | ✅ | ✅ | ⚠️ | ⚠️ |
+| **Shared validation** | N/A | ❌ | ✅ | ⚠️ |
+| **Commands share logic** | N/A | ⚠️ | ✅ | ⚠️ |
+| **Exit codes** | ⚠️ | ⚠️ | ⚠️ | ✅ |
+| **Dependency injection** | ❌ | ❌ | ❌ | ✅ |
+| **Professional-grade** | Simple only | Medium tools | ✅ | ✅✅ |
 
 Legend:
 - ✅ Excellent fit
@@ -125,17 +173,48 @@ lib/appydave/tools/youtube_manager/
 Total: 6+ files (2 commands)
 ```
 
+### Pattern 4 (jump)
+```
+bin/jump.rb                                  1 file (30 lines!)
+lib/appydave/tools/jump/
+  ├── cli.rb                                 1 file (400+ lines)
+  ├── config.rb                              1 file
+  ├── search.rb                              1 file
+  ├── crud.rb                                1 file
+  ├── validators/
+  │   └── path_validator.rb                  1 file
+  ├── formatters/
+  │   ├── table_formatter.rb                 3 files
+  │   ├── json_formatter.rb
+  │   └── paths_formatter.rb
+  └── generators/
+      └── aliases_generator.rb               1 file
+────────────────────────────────────────────
+Total: 10+ files (10 commands)
+```
+
 ## Code Volume Comparison
 
-For a tool with **2 commands** (get, update):
+### For a tool with 2 commands (get, update):
 
 | Pattern | Lines of Code | Files | Boilerplate |
 |---------|---------------|-------|-------------|
 | Pattern 1 | N/A | N/A | Not applicable |
 | Pattern 2 | ~150 LOC | 3 | Low |
 | Pattern 3 | ~200 LOC | 6 | Medium |
+| Pattern 4 | ~250 LOC | 4 | Medium |
+
+**Recommendation:** Use Pattern 2 for 2-5 commands
 
-**Recommendation:** Use Pattern 2 for 2-5 commands, switch to Pattern 3 at 6+
+### For a tool with 10 commands:
+
+| Pattern | bin/ LOC | lib/ LOC | Total LOC | Files |
+|---------|----------|----------|-----------|-------|
+| Pattern 2 | 800-1600 | 500 | 1300-2100 | 11 |
+| Pattern 3 | 80 | 2000+ | 2080+ | 21+ |
+| Pattern 4 | 30 | 1500+ | 1530+ | 10+ |
+
+**Recommendation:** Use Pattern 4 for 10+ commands (cleaner, testable)
 
 ## When to Refactor Between Patterns
 
@@ -145,13 +224,32 @@ For a tool with **2 commands** (get, update):
 **Effort:** Medium - Requires restructuring bin/ file
 
 ### Pattern 2 → Pattern 3
-**Trigger:** 
-- Command count reaches 6+
+**Trigger:**
+- Command count reaches 6-9
 - Commands share significant validation logic
 - Need consistent error handling across commands
+- Don't need CLI testing
 
 **Effort:** Medium-High - Create BaseAction, convert methods to Action classes
 
+### Pattern 2 → Pattern 4
+**Trigger:**
+- Command count reaches 10+
+- bin/ file exceeds 500 lines
+- Want to test CLI behavior
+- Building professional-grade tool
+
+**Effort:** Medium - Move CLI class to lib/, add dependency injection, create CLI tests
+
+### Pattern 3 → Pattern 4
+**Trigger:**
+- Want to test CLI behavior (exit codes, output)
+- Need dependency injection for testing
+- Commands growing beyond 10+
+- BaseAction pattern feels constraining
+
+**Effort:** Medium - Convert Actions to methods in CLI class, add dependency injection
+
 ## Real-World Examples
 
 ### Pattern 1: gpt_context
@@ -196,6 +294,38 @@ For a tool with **2 commands** (get, update):
 - Future commands: `delete`, `upload`, `list`, `analyze`
 - Shared pattern: authorize → validate → execute → report
 
+---
+
+### Pattern 4: jump
+**Purpose:** Manage development folder locations
+
+**Commands:** 10
+- `search` - Fuzzy search locations
+- `get` - Get by exact key
+- `list` - List all locations
+- `add` - Add new location
+- `update` - Update existing location
+- `remove` - Remove location
+- `validate` - Validate paths exist
+- `report` - Generate reports
+- `generate` - Generate shell aliases
+- `info` - Show configuration info
+
+**Why Pattern 4?**
+- 10 commands - Too many for Pattern 2/3
+- Want to test CLI behavior (exit codes, output formatting)
+- Professional development tool (needs dependency injection)
+- Complex CLI logic (400+ lines in lib/cli.rb)
+- Multiple output formatters (table, json, paths)
+- Comprehensive help system
+
+**Key benefits:**
+- ✅ Full RSpec test coverage of CLI behavior
+- ✅ Mock config, validators in tests
+- ✅ Test exit codes (0 = success, 1-4 = different errors)
+- ✅ Thin bin/ wrapper (29 lines)
+- ✅ Professional-grade architecture
+
 ## Anti-Patterns to Avoid
 
 ### ❌ Don't: Mix patterns
@@ -271,8 +401,8 @@ When migrating an existing tool or creating a new one:
 - [ ] Implement business logic in `lib/`
 - [ ] Add `# frozen_string_literal: true`
 - [ ] No `require` statements in `lib/` (except Ruby stdlib)
-- [ ] No CLI code in `lib/` classes
-- [ ] Write RSpec tests for business logic
+- [ ] No CLI code in `lib/` classes (except Pattern 4: CLI in lib/cli.rb)
+- [ ] Write RSpec tests for business logic (Pattern 4: also test CLI class)
 - [ ] Register in `appydave-tools.gemspec`
 - [ ] Document in `CLAUDE.md`
 - [ ] Create `_doc.md` in module directory
@@ -281,4 +411,4 @@ When migrating an existing tool or creating a new one:
 
 ---
 
-**Last updated:** 2025-11-08
+**Last updated:** 2025-02-04