appydave-tools 0.70.0 → 0.71.0

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

@@ -0,0 +1,233 @@
+# frozen_string_literal: true
+
+module Appydave
+  module Tools
+    module Jump
+      # Config manages the locations.json configuration file
+      #
+      # Follows the same pattern as other configuration models in appydave-tools,
+      # using ConfigBase for file loading/saving with automatic backups.
+      #
+      # @example Basic usage
+      #   config = Config.new
+      #   config.locations          # => Array of Location objects
+      #   config.brands             # => Hash of brand definitions
+      #   config.find('ad-tools')   # => Location or nil
+      class Config
+        include KLog::Logging
+
+        CONFIG_VERSION = '1.0'
+        DEFAULT_CONFIG_NAME = 'locations'
+
+        attr_reader :data, :config_path
+
+        def initialize(config_path: nil)
+          @config_path = config_path || default_config_path
+          @data = load_config
+        end
+
+        # Get all locations as Location objects
+        #
+        # @return [Array<Location>]
+        def locations
+          @locations ||= (data['locations'] || []).map { |loc| Location.new(loc) }
+        end
+
+        # Reload locations from data (after modifications)
+        def reload_locations
+          @locations = nil
+          locations
+        end
+
+        # Get brand definitions
+        #
+        # @return [Hash]
+        def brands
+          data['brands'] || {}
+        end
+
+        # Get client definitions
+        #
+        # @return [Hash]
+        def clients
+          data['clients'] || {}
+        end
+
+        # Get category definitions
+        #
+        # @return [Hash]
+        def categories
+          data['categories'] || {}
+        end
+
+        # Get metadata
+        #
+        # @return [Hash]
+        def meta
+          data['meta'] || {}
+        end
+
+        # Find a location by key
+        #
+        # @param key [String] Location key
+        # @return [Location, nil]
+        def find(key)
+          locations.find { |loc| loc.key == key }
+        end
+
+        # Check if a location key exists
+        #
+        # @param key [String] Location key
+        # @return [Boolean]
+        def key_exists?(key)
+          locations.any? { |loc| loc.key == key }
+        end
+
+        # Add a new location
+        #
+        # @param location [Location, Hash] Location to add
+        # @return [Boolean] true if added successfully
+        # @raise [ArgumentError] if key already exists or location is invalid
+        def add(location)
+          location = Location.new(location) if location.is_a?(Hash)
+
+          raise ArgumentError, "Location key '#{location.key}' already exists" if key_exists?(location.key)
+
+          errors = location.validate
+          raise ArgumentError, "Invalid location: #{errors.join(', ')}" unless errors.empty?
+
+          data['locations'] ||= []
+          data['locations'] << location.to_h
+          reload_locations
+          true
+        end
+
+        # Update an existing location
+        #
+        # @param key [String] Key of location to update
+        # @param attrs [Hash] Attributes to update
+        # @return [Boolean] true if updated successfully
+        # @raise [ArgumentError] if location not found or updates are invalid
+        def update(key, attrs)
+          index = (data['locations'] || []).find_index { |loc| loc['key'] == key || loc[:key] == key }
+          raise ArgumentError, "Location '#{key}' not found" if index.nil?
+
+          # Merge attributes
+          current = data['locations'][index].transform_keys(&:to_sym)
+          updated_attrs = current.merge(attrs.transform_keys(&:to_sym))
+
+          # Validate
+          updated = Location.new(updated_attrs)
+          errors = updated.validate
+          raise ArgumentError, "Invalid update: #{errors.join(', ')}" unless errors.empty?
+
+          data['locations'][index] = updated.to_h.transform_keys(&:to_s)
+          reload_locations
+          true
+        end
+
+        # Remove a location by key
+        #
+        # @param key [String] Key of location to remove
+        # @return [Boolean] true if removed
+        # @raise [ArgumentError] if location not found
+        def remove(key)
+          index = (data['locations'] || []).find_index { |loc| loc['key'] == key || loc[:key] == key }
+          raise ArgumentError, "Location '#{key}' not found" if index.nil?
+
+          data['locations'].delete_at(index)
+          reload_locations
+          true
+        end
+
+        # Save configuration to file with backup
+        #
+        # @return [void]
+        def save
+          # Create backup if file exists
+          if File.exist?(config_path)
+            backup_path = "#{config_path}.backup.#{Time.now.strftime('%Y%m%d-%H%M%S')}"
+            FileUtils.cp(config_path, backup_path)
+          end
+
+          # Update timestamp
+          data['meta'] ||= {}
+          data['meta']['version'] = CONFIG_VERSION
+          data['meta']['last_updated'] = Time.now.utc.iso8601
+
+          # Ensure directory exists
+          FileUtils.mkdir_p(File.dirname(config_path))
+
+          # Write atomically (temp file then rename)
+          temp_path = "#{config_path}.tmp"
+          File.write(temp_path, JSON.pretty_generate(data))
+          File.rename(temp_path, config_path)
+        end
+
+        # Update validation timestamp
+        #
+        # @return [void]
+        def touch_validated
+          data['meta'] ||= {}
+          data['meta']['last_validated'] = Time.now.utc.iso8601
+        end
+
+        # Get info about the configuration
+        #
+        # @return [Hash]
+        def info
+          {
+            config_path: config_path,
+            exists: File.exist?(config_path),
+            version: meta['version'],
+            last_updated: meta['last_updated'],
+            last_validated: meta['last_validated'],
+            location_count: locations.size,
+            brand_count: brands.size,
+            client_count: clients.size
+          }
+        end
+
+        private
+
+        def default_config_path
+          File.join(Configuration::Config.config_path, "#{DEFAULT_CONFIG_NAME}.json")
+        end
+
+        def load_config
+          return default_data unless File.exist?(config_path)
+
+          content = File.read(config_path)
+          JSON.parse(content)
+        rescue JSON::ParserError => e
+          log.error "JSON parse error in #{config_path}: #{e.message}"
+          default_data
+        rescue StandardError => e
+          log.error "Error loading #{config_path}: #{e.message}"
+          default_data
+        end
+
+        def default_data
+          {
+            'meta' => {
+              'version' => CONFIG_VERSION
+            },
+            'categories' => {
+              'type' => {
+                'description' => 'Kind of location',
+                'values' => %w[brand client gem video brain site tool config]
+              },
+              'technology' => {
+                'description' => 'Primary language/framework',
+                'values' => %w[ruby javascript typescript python astro]
+              }
+            },
+            'brands' => {},
+            'clients' => {},
+            'locations' => []
+          }
+        end
+      end
+    end
+  end
+end

data/lib/appydave/tools/jump/formatters/base.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Appydave
+  module Tools
+    module Jump
+      module Formatters
+        # Base formatter class providing common functionality
+        class Base
+          attr_reader :data, :options
+
+          def initialize(data, options = {})
+            @data = data
+            @options = options
+          end
+
+          # Format the data
+          #
+          # @return [String] Formatted output
+          def format
+            raise NotImplementedError, 'Subclasses must implement #format'
+          end
+
+          protected
+
+          def results
+            data[:results] || []
+          end
+
+          def success?
+            data[:success]
+          end
+
+          def error_message
+            data[:error]
+          end
+
+          def suggestion
+            data[:suggestion]
+          end
+
+          def count
+            data[:count] || 0
+          end
+        end
+      end
+    end
+  end
+end

data/lib/appydave/tools/jump/formatters/json_formatter.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Appydave
+  module Tools
+    module Jump
+      module Formatters
+        # JSON formatter for programmatic access and Claude skill integration
+        class JsonFormatter < Base
+          # Format data as JSON
+          #
+          # @return [String] JSON string
+          def format
+            JSON.pretty_generate(data)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/appydave/tools/jump/formatters/paths_formatter.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Appydave
+  module Tools
+    module Jump
+      module Formatters
+        # Paths formatter outputs one path per line for scripting
+        class PathsFormatter < Base
+          # Format data as one path per line
+          #
+          # @return [String] Newline-separated paths
+          def format
+            return '' unless success?
+
+            results.map { |r| r[:path] }.compact.join("\n")
+          end
+        end
+      end
+    end
+  end
+end

data/lib/appydave/tools/jump/formatters/table_formatter.rb

@@ -0,0 +1,183 @@
+# frozen_string_literal: true
+
+module Appydave
+  module Tools
+    module Jump
+      module Formatters
+        # Table formatter for human-readable terminal output with colors
+        class TableFormatter < Base
+          # ANSI color codes
+          COLORS = {
+            reset: "\e[0m",
+            bold: "\e[1m",
+            dim: "\e[2m",
+            red: "\e[31m",
+            green: "\e[32m",
+            yellow: "\e[33m",
+            blue: "\e[34m",
+            magenta: "\e[35m",
+            cyan: "\e[36m",
+            white: "\e[37m"
+          }.freeze
+
+          # Format data as a colored table
+          #
+          # @return [String] Formatted table
+          def format
+            return format_error unless success?
+            return format_info if info_result?
+            return format_empty if results.empty?
+
+            format_results
+          end
+
+          private
+
+          def format_error
+            lines = []
+            lines << colorize("Error: #{error_message}", :red)
+            lines << colorize(suggestion, :yellow) if suggestion
+            lines.join("\n")
+          end
+
+          def format_empty
+            colorize('No locations found.', :yellow)
+          end
+
+          def info_result?
+            data.key?(:config_path)
+          end
+
+          def format_info
+            [
+              format_info_header,
+              format_info_details,
+              format_info_statistics
+            ].join("\n")
+          end
+
+          def format_info_header
+            [
+              colorize('Jump Location Tool - Configuration Info', :bold),
+              ''
+            ]
+          end
+
+          def format_info_details
+            exists_value = data[:exists] ? colorize('Yes', :green) : colorize('No', :red)
+            [
+              "#{colorize('Config Path:', :cyan)}  #{data[:config_path]}",
+              "#{colorize('Config Exists:', :cyan)} #{exists_value}",
+              "#{colorize('Version:', :cyan)}       #{data[:version] || 'N/A'}",
+              "#{colorize('Last Updated:', :cyan)}  #{data[:last_updated] || 'Never'}",
+              "#{colorize('Last Validated:', :cyan)} #{data[:last_validated] || 'Never'}",
+              ''
+            ]
+          end
+
+          def format_info_statistics
+            [
+              colorize('Statistics:', :bold),
+              "  Locations: #{data[:location_count] || 0}",
+              "  Brands:    #{data[:brand_count] || 0}",
+              "  Clients:   #{data[:client_count] || 0}"
+            ]
+          end
+
+          def format_results
+            lines = []
+
+            # Header
+            lines << format_header
+            lines << header_separator
+
+            # Results
+            results.each do |result|
+              lines << format_row(result)
+            end
+
+            # Footer
+            lines << ''
+            lines << colorize("Total: #{count} location(s)", :dim)
+
+            lines.join("\n")
+          end
+
+          def format_header
+            cols = [
+              pad('#', 3),
+              pad('KEY', key_width),
+              pad('JUMP', jump_width),
+              pad('TYPE', 10),
+              pad('BRAND/CLIENT', 15),
+              'DESCRIPTION'
+            ]
+            colorize(cols.join('  '), :bold)
+          end
+
+          def header_separator
+            '-' * terminal_width
+          end
+
+          # rubocop:disable Metrics/AbcSize
+          def format_row(result)
+            index = result[:index].to_s.rjust(3)
+            key = pad(result[:key] || '', key_width)
+            jump = pad(result[:jump] || '', jump_width)
+            type = pad(result[:type] || '', 10)
+            owner = pad(result[:brand] || result[:client] || '', 15)
+            desc = truncate(result[:description] || '', description_width)
+
+            # Color the score indicator
+            score_indicator = if result[:score]&.positive?
+                                colorize("[#{result[:score]}]", :cyan)
+                              else
+                                ''
+                              end
+
+            "#{colorize(index, :dim)}  #{colorize(key, :green)}  #{colorize(jump, :blue)}  " \
+              "#{type}  #{colorize(owner, :magenta)}  #{desc} #{score_indicator}"
+          end
+          # rubocop:enable Metrics/AbcSize
+
+          def key_width
+            @key_width ||= [results.map { |r| (r[:key] || '').length }.max || 10, 20].min
+          end
+
+          def jump_width
+            @jump_width ||= [results.map { |r| (r[:jump] || '').length }.max || 10, 15].min
+          end
+
+          def description_width
+            @description_width ||= [terminal_width - 60, 30].max
+          end
+
+          def terminal_width
+            @terminal_width ||= begin
+              width = ENV.fetch('COLUMNS', nil)&.to_i
+              width = `tput cols 2>/dev/null`.to_i if width.nil? || width.zero?
+              width = 120 if width.zero?
+              width
+            end
+          end
+
+          def pad(str, width)
+            str.to_s.ljust(width)[0...width]
+          end
+
+          def truncate(str, width)
+            return str if str.length <= width
+
+            "#{str[0...(width - 3)]}..."
+          end
+
+          def colorize(text, color)
+            return text unless options[:color] != false && $stdout.tty?
+
+            "#{COLORS[color]}#{text}#{COLORS[:reset]}"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/appydave/tools/jump/location.rb

@@ -0,0 +1,134 @@
+# frozen_string_literal: true
+
+module Appydave
+  module Tools
+    module Jump
+      # Location represents a single development folder location
+      #
+      # @example Creating a location
+      #   location = Location.new(
+      #     key: 'ad-tools',
+      #     path: '~/dev/ad/appydave-tools',
+      #     jump: 'jad-tools',
+      #     brand: 'appydave',
+      #     type: 'tool',
+      #     tags: ['ruby', 'cli'],
+      #     description: 'AppyDave CLI tools'
+      #   )
+      class Location
+        VALID_KEY_PATTERN = /\A[a-z0-9][a-z0-9-]*[a-z0-9]\z|\A[a-z0-9]\z/.freeze
+        VALID_PATH_PATTERN = %r{\A[~/]}.freeze
+        VALID_TAG_PATTERN = /\A[a-z0-9][a-z0-9-]*[a-z0-9]\z|\A[a-z0-9]\z/.freeze
+
+        attr_reader :key, :path, :jump, :brand, :client, :type, :tags, :description
+
+        def initialize(attrs = {})
+          attrs = normalize_attrs(attrs)
+
+          @key = attrs[:key]
+          @path = attrs[:path]
+          @jump = attrs[:jump] || default_jump
+          @brand = attrs[:brand]
+          @client = attrs[:client]
+          @type = attrs[:type]
+          @tags = Array(attrs[:tags])
+          @description = attrs[:description]
+        end
+
+        # Validate the location
+        #
+        # @return [Array<String>] List of validation errors (empty if valid)
+        def validate
+          errors = []
+          errors << 'Key is required' if key.nil? || key.empty?
+          errors << "Key '#{key}' is invalid (must be lowercase alphanumeric with hyphens)" if key && !valid_key?
+          errors << 'Path is required' if path.nil? || path.empty?
+          errors << "Path '#{path}' is invalid (must start with ~ or /)" if path && !valid_path?
+          errors.concat(validate_tags)
+          errors
+        end
+
+        # Check if location is valid
+        #
+        # @return [Boolean]
+        def valid?
+          validate.empty?
+        end
+
+        # Convert to hash for JSON serialization
+        #
+        # @return [Hash]
+        def to_h
+          {
+            key: key,
+            path: path,
+            jump: jump,
+            brand: brand,
+            client: client,
+            type: type,
+            tags: tags,
+            description: description
+          }.compact
+        end
+
+        # Get all searchable text for this location
+        #
+        # @param brands [Hash] Brand definitions with aliases
+        # @param clients [Hash] Client definitions with aliases
+        # @return [Array<String>] All searchable terms
+        def searchable_terms(brands: {}, clients: {})
+          terms = [key, path, type, description].compact
+          terms.concat(tags)
+
+          # Add brand and its aliases
+          if brand && brands[brand]
+            terms << brand
+            terms.concat(Array(brands[brand]['aliases'] || brands[brand][:aliases]))
+          elsif brand
+            terms << brand
+          end
+
+          # Add client and its aliases
+          if client && clients[client]
+            terms << client
+            terms.concat(Array(clients[client]['aliases'] || clients[client][:aliases]))
+          elsif client
+            terms << client
+          end
+
+          terms.compact.map(&:to_s).map(&:downcase)
+        end
+
+        private
+
+        def normalize_attrs(attrs)
+          attrs.transform_keys(&:to_sym)
+        end
+
+        def default_jump
+          return nil unless key
+
+          "j#{key}"
+        end
+
+        def valid_key?
+          key.match?(VALID_KEY_PATTERN)
+        end
+
+        def valid_path?
+          path.match?(VALID_PATH_PATTERN)
+        end
+
+        def validate_tags
+          errors = []
+          tags.each do |tag|
+            next if tag.match?(VALID_TAG_PATTERN)
+
+            errors << "Tag '#{tag}' is invalid (must be lowercase alphanumeric with hyphens)"
+          end
+          errors
+        end
+      end
+    end
+  end
+end

data/lib/appydave/tools/jump/path_validator.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Appydave
+  module Tools
+    module Jump
+      # PathValidator checks if filesystem paths exist
+      #
+      # This class is designed for dependency injection in tests.
+      # Production code uses the real filesystem, while tests inject
+      # a mock that returns predetermined results.
+      #
+      # @example Production usage
+      #   validator = PathValidator.new
+      #   validator.exists?('~/dev/project')  # => true/false based on real filesystem
+      #
+      # @example Test usage (see spec/support/jump_test_helpers.rb)
+      #   validator = TestPathValidator.new(valid_paths: ['~/dev/project'])
+      #   validator.exists?('~/dev/project')  # => true
+      #   validator.exists?('~/dev/other')    # => false
+      class PathValidator
+        # Check if a path exists as a directory
+        #
+        # @param path [String] Path to check (supports ~ expansion)
+        # @return [Boolean] true if directory exists
+        def exists?(path)
+          File.directory?(expand(path))
+        end
+
+        # Check if a path exists as a file
+        #
+        # @param path [String] Path to check (supports ~ expansion)
+        # @return [Boolean] true if file exists
+        def file_exists?(path)
+          File.exist?(expand(path))
+        end
+
+        # Expand a path (resolve ~ and relative paths)
+        #
+        # @param path [String] Path to expand
+        # @return [String] Absolute path
+        def expand(path)
+          File.expand_path(path)
+        end
+      end
+    end
+  end
+end