cline-rb 1.0.0

data/lib/cline/schema.rb

@@ -0,0 +1,144 @@
+require 'json'
+require 'shale'
+
+module Cline
+  # Base class for any Cline domain object that defines some attributes that are serializable in JSON.
+  # Handle the following features:
+  # * Provide Shale attributes interface.
+  # * Automatically transforms Cline camelCase naming.
+  # * Keep track of extra attributes to serialize them back if needed.
+  class Schema < Shale::Mapper
+    # @!group Internal
+
+    # @return [Hash] Store all extra values from a JSON parse
+    attr_accessor :extra_attributes
+
+    class << self
+      # Define the attributes that are already in snake case in Cline files
+      #
+      # @param attributes [Array<Symbol>] List of attributes already in snake case
+      def cline_snake_attributes(*attributes)
+        @snake_attributes ||= []
+        @snake_attributes.concat(attributes)
+        @snake_attributes.uniq!
+      end
+
+      # Parse a Hash object and instantiate the proper instance from it.
+      #
+      # @param hash [Hash] Data
+      # @param args [Array] Remaining arguments to be transferred to Shale
+      # @param kwargs [Hash] Remaining kwargs to be transferred to Shale
+      # @return [Schema] Corresponding instance
+      def of_hash(hash, *args, **kwargs)
+        complete_hash_mapping
+        known = hash_mapping.keys.keys
+        # Separate unknown attributes.
+        known_hash = {}
+        extra_hash = {}
+        hash.each do |key, value|
+          if known.include?(key)
+            known_hash[key] = value
+          else
+            extra_hash[key] = value
+          end
+        end
+        # Give Shale the data it knows about, without extra attributes
+        instance = super(known_hash, *args, **kwargs)
+        instance.extra_attributes = extra_hash unless extra_hash.empty?
+        instance
+      end
+
+      # Get a Hash object from an instance.
+      #
+      # @param instance [Schema] Object to serialize to a Hash
+      # @param args [Array] Remaining arguments to be transferred to Shale
+      # @param kwargs [Hash] Remaining kwargs to be transferred to Shale
+      # @return [Hash] Corresponding hash
+      def as_hash(instance, *args, **kwargs)
+        complete_hash_mapping
+        hash = super
+        hash.merge!(instance.extra_attributes) if instance.extra_attributes
+        hash
+      end
+
+      # Cast an input value to this Schema object.
+      # Allow the attribute to be initialized directly using its Hash form.
+      #
+      # @param value [Schema, Hash, nil] The value that could be used to initialize a new instance of this attribute.
+      # @return [Schema, nil] The corresponding instance, or nil if none.
+      def cast(value)
+        return nil if value.nil?
+
+        # We expect the value to be either a Hash that can be used to initialize a new instance, or a new instance already initialized.
+        if value.is_a?(self)
+          value
+        elsif value.is_a?(Hash)
+          new(**value)
+        else
+          raise "Unable to cast #{value} into #{name}"
+        end
+      end
+
+      private
+
+      # Complete the hash mapping to include camelCase to snake_case as the defaults.
+      # Do it only once.
+      def complete_hash_mapping
+        return if @hash_mapping_completed
+
+        snake_attributes = @snake_attributes || []
+        # Find the hash name that we expect for each attribute name
+        attributes_mapping = attributes.keys.to_h do |attribute|
+          [
+            attribute,
+            if snake_attributes.include?(attribute)
+              attribute.to_s
+            else
+              attribute.to_s.gsub(/(?<!_)_([a-zA-Z0-9])(?!_)/) { Regexp.last_match(1).upcase }
+            end
+          ]
+        end
+
+        # Redefine the hash mapping for all expected attributes
+        hsh do
+          attributes_mapping.each do |attribute, hash_attribute|
+            # Find the hash name that we expect for each attribute name
+            map hash_attribute, to: attribute
+          end
+        end
+        @hash_mapping_completed = true
+      end
+    end
+
+    # Output this object as Cline JSON.
+    #
+    # @return [String] Cline JSON
+    def to_cline_json
+      JSON.dump(self.class.as_hash(self))
+    end
+
+    # Output this object as a Hash.
+    #
+    # @return [Hash] Cline JSON
+    def to_hash
+      hash = self.class.attributes.to_h do |attribute|
+        value = send(attribute.to_sym)
+        [
+          attribute,
+          value.respond_to?(:to_hash) ? value.to_hash : value
+        ]
+      end
+      hash.merge!(extra_attributes:) if extra_attributes
+      hash
+    end
+
+    # Equality check
+    #
+    # @param other [Object] The other to check equality with
+    # @return [Boolean] True if objects are equal
+    def ==(other)
+      other.is_a?(Schema) &&
+        other.to_hash == to_hash
+    end
+  end
+end

data/lib/cline/secret_string.rb

@@ -0,0 +1,83 @@
+require 'secret_string'
+
+module Cline
+  # ::SecretString wrapper that allows us to use it in our Shale schemas
+  class SecretString < Schema
+    extend Forwardable
+
+    # @!group Public API
+
+    def_delegators :secret_string, *%i[to_s to_unprotected]
+
+    # Equality check
+    #
+    # @param other [Object] The other to check equality with
+    # @return [Boolean] True if objects are equal
+    def ==(other)
+      other.is_a?(SecretString) &&
+        other.to_unprotected == to_unprotected
+    end
+
+    # @!group Internal
+
+    # Constructor
+    #
+    # @param unprotected_string [String] The unprotected string
+    def initialize(unprotected_string)
+      super()
+      @secret_string = ::SecretString.new(unprotected_string)
+    end
+
+    # @return [Hash] The internal secret string
+    attr_reader :secret_string
+
+    # Output this object as a Hash.
+    #
+    # @return [Hash] Cline JSON
+    def to_hash
+      SecretString.as_hash(self)
+    end
+
+    class << self
+      # @!group Internal
+
+      # Parse a Hash object and instantiate the proper instance from it.
+      #
+      # @param hash [Hash] Data
+      # @param _args [Array] Remaining arguments to be transferred to Shale
+      # @param _kwargs [Hash] Remaining kwargs to be transferred to Shale
+      # @return [Schema] Corresponding instance
+      def of_hash(hash, *_args, **_kwargs)
+        SecretString.new(hash)
+      end
+
+      # Get a Hash object from an instance.
+      #
+      # @param instance [Schema] Object to serialize to a Hash
+      # @param _args [Array] Remaining arguments to be transferred to Shale
+      # @param _kwargs [Hash] Remaining kwargs to be transferred to Shale
+      # @return [Hash] Corresponding hash
+      def as_hash(instance, *_args, **_kwargs)
+        instance.secret_string.to_unprotected
+      end
+
+      # Cast an input value to this Schema object.
+      # Allow the attribute to be initialized directly using its Hash form.
+      #
+      # @param value [Schema, String, nil] The value that could be used to initialize a new instance of this attribute.
+      # @return [Schema, nil] The corresponding instance, or nil if none.
+      def cast(value)
+        return nil if value.nil?
+
+        # We expect the value to be a String, or a new instance already initialized.
+        if value.is_a?(self)
+          value
+        elsif value.is_a?(String)
+          new(value)
+        else
+          raise "Unable to cast #{value} into #{name}"
+        end
+      end
+    end
+  end
+end

data/lib/cline/secrets.rb

@@ -0,0 +1,119 @@
+module Cline
+  # Access secrets stored in the data directory's secrets.json file
+  class Secrets < Schema
+    # @!group Public API
+
+    Serializable::ClineData.include_for(self, 'secrets.json')
+
+    # @return [SecretString, nil] Cline API key
+    attribute :cline_api_key, SecretString
+
+    # @return [SecretString, nil] OpenAI API key
+    attribute :open_ai_api_key, SecretString
+
+    # @return [SecretString, nil] Gemini API key
+    attribute :gemini_api_key, SecretString
+
+    # @return [SecretString, nil] Generic API key
+    attribute :api_key, SecretString
+
+    # @return [SecretString, nil] AWS access key
+    attribute :aws_access_key, SecretString
+
+    # @return [SecretString, nil] AWS secret key
+    attribute :aws_secret_key, SecretString
+
+    # @return [SecretString, nil] AWS session token
+    attribute :aws_session_token, SecretString
+
+    # @return [SecretString, nil] DeepSeek API key
+    attribute :deep_seek_api_key, SecretString
+
+    # @return [SecretString, nil] OpenAI native API key
+    attribute :open_ai_native_api_key, SecretString
+
+    # @return [SecretString, nil] OpenRouter API key
+    attribute :open_router_api_key, SecretString
+
+    # @return [SecretString, nil] LiteLLM API key
+    attribute :lite_llm_api_key, SecretString
+
+    # @return [SecretString, nil] SAP AI Core client ID
+    attribute :sap_ai_core_client_id, SecretString
+
+    # @return [SecretString, nil] SAP AI Core client secret
+    attribute :sap_ai_core_client_secret, SecretString
+
+    # @return [SecretString, nil] Mistral API key
+    attribute :mistral_api_key, SecretString
+
+    # @return [SecretString, nil] ZAI API key
+    attribute :zai_api_key, SecretString
+
+    # @return [SecretString, nil] Groq API key
+    attribute :groq_api_key, SecretString
+
+    # @return [SecretString, nil] Cerebras API key
+    attribute :cerebras_api_key, SecretString
+
+    # @return [SecretString, nil] Vercel AI Gateway API key
+    attribute :vercel_ai_gateway_api_key, SecretString
+
+    # @return [SecretString, nil] Baseten API key
+    attribute :baseten_api_key, SecretString
+
+    # @return [SecretString, nil] Requesty API key
+    attribute :requesty_api_key, SecretString
+
+    # @return [SecretString, nil] Fireworks API key
+    attribute :fireworks_api_key, SecretString
+
+    # @return [SecretString, nil] Together API key
+    attribute :together_api_key, SecretString
+
+    # @return [SecretString, nil] Qwen API key
+    attribute :qwen_api_key, SecretString
+
+    # @return [SecretString, nil] Doubao API key
+    attribute :doubao_api_key, SecretString
+
+    # @return [SecretString, nil] Moonshot API key
+    attribute :moonshot_api_key, SecretString
+
+    # @return [SecretString, nil] HuggingFace API key
+    attribute :hugging_face_api_key, SecretString
+
+    # @return [SecretString, nil] Nebius API key
+    attribute :nebius_api_key, SecretString
+
+    # @return [SecretString, nil] AskSage API key
+    attribute :asksage_api_key, SecretString
+
+    # @return [SecretString, nil] xAI API key
+    attribute :xai_api_key, SecretString
+
+    # @return [SecretString, nil] Sambanova API key
+    attribute :sambanova_api_key, SecretString
+
+    # @return [SecretString, nil] Huawei Cloud Maas API key
+    attribute :huawei_cloud_maas_api_key, SecretString
+
+    # @return [SecretString, nil] Dify API key
+    attribute :dify_api_key, SecretString
+
+    # @return [SecretString, nil] Minimax API key
+    attribute :minimax_api_key, SecretString
+
+    # @return [SecretString, nil] Hicap API key
+    attribute :hicap_api_key, SecretString
+
+    # @return [SecretString, nil] AIHubMix API key
+    attribute :aihubmix_api_key, SecretString
+
+    # @return [SecretString, nil] Nous Research API key
+    attribute :nous_research_api_key, SecretString
+
+    # @return [SecretString, nil] Weights & Biases API key
+    attribute :wandb_api_key, SecretString
+  end
+end

data/lib/cline/serializable/cline_data.rb

@@ -0,0 +1,131 @@
+module Cline
+  # List of mixins that provide serialization/deserialization features on other objects.
+  module Serializable
+    # Add features to initialize from and save an object to Cline data.
+    # Cline data is defined as a JSON file, relative to a base directory.
+    # This mixin is intended to be included using the `.include_for(self, cline_json_file)` method.
+    #
+    # Provides:
+    # - `.from_cline_data(base_dir) -> [Object, nil]` Provides a new instance initialized from a Cline JSON file present in a base directory.
+    # - `.monitor_cline_data_changes(base_dir, on_change)` Provides a monitor to be notified on Cline data changes.
+    # - `#to_cline_data(base_dir)` Save an instance in the Cline data.
+    #
+    # Requires:
+    # - `.of_hash(hash) -> Object` The deserializer that returns an instance from a JSON object.
+    # - `#to_cline_json -> String` The serializer that returns a JSON string from the instance.
+    module ClineData
+      # @!group Public API
+
+      # Save the instance into the Cline data
+      def save
+        raise 'This instance has not been initialized from a Cline file' unless file
+
+        FileUtils.mkdir_p(::File.dirname(file))
+        ::File.write(file, to_cline_json)
+      end
+
+      # @!group Internal
+
+      # Class methods that should be made accessible to any class including our mixin
+      module ClassMethods
+        # @!group Internal
+
+        # Instantiate an instance of the including class from a base directory.
+        #
+        # @param base_dir [String] Base directory used to initialize the new instance
+        # @param args [Array] Extra parameters to give to the instance's constructor
+        # @param create [Boolean] Should data be created if it does not exist?
+        # @param kwargs [Hash] Extra kwargs to give to the instance's constructor
+        # @return [Object, nil] The instance, or nil if no Cline data exists
+        def from_cline_data(base_dir, *args, create: false, **kwargs)
+          instance = self.open(
+            ::File.join(base_dir, cline_json_file(base_dir)),
+            *args,
+            default: create ? '{}' : nil,
+            **kwargs
+          )
+          return unless instance
+
+          instance.initialize_from_dir(base_dir, create:)
+          instance
+        end
+
+        # Monitor changes done on the file and call a callback for each update.
+        #
+        # @param base_dir [String] Base directory used to initialize the new instance
+        # @param args [Array] Extra parameters to give to the instance's constructor
+        # @param on_change [#call] Block called each time there is an update.
+        #   * Param instance [Object, nil] New instance with updates, or nil if no instance
+        # @param monitoring_interval_secs [Float] The monitoring interval in seconds
+        # @param kwargs [Hash] Extra kwargs to give to the instance's constructor
+        # @yield Optional code called while monitoring is in place.
+        #   If used then monitoring is stopped at the end of the block's execution.
+        # @return [Utils::FileMonitor, nil] If no block has been given, return the monitor that needs to be
+        #   stopped by the caller when monitoring should end.
+        def monitor_cline_data_changes(base_dir, *args, on_change:, monitoring_interval_secs: 1, **kwargs, &)
+          monitor_updates(
+            ::File.join(base_dir, cline_json_file(base_dir)),
+            *args,
+            on_change: proc do |instance|
+              instance.initialize_from_dir(base_dir, create: false)
+              on_change.call(instance)
+            end,
+            monitoring_interval_secs:,
+            **kwargs,
+            &
+          )
+        end
+
+        # Default factory for instances.
+        # This could be overriden by some classes that need to instantiate differently.
+        #
+        # @param file [String] File to initialize from.
+        # @param args [Array] Extra parameters to give to the instance's constructor.
+        # @param kwargs [Hash] Extra kwargs to give to the instance's constructor.
+        # @return [Object] A new instance.
+        def new_instance(file, *args, **kwargs)
+          of_hash(Utils::File.safe_json_read(file), *args, **kwargs)
+        end
+
+        private
+
+        # Get the relative JSON file path from the base directory
+        #
+        # @param base_dir [String] The base directory
+        # @return [String] The relative JSON file path
+        def cline_json_file(base_dir)
+          cline_json_file_def.is_a?(Proc) ? cline_json_file_def.call(base_dir) : cline_json_file_def
+        end
+      end
+
+      # Include the mixin and configure it with the JSON file path
+      #
+      # @param calling_class [Class] The class that is calling this method.
+      # @param cline_json_file_def [String, #call] The definition of the relative JSON file path to use. Can be one of:
+      #   - [String] The static relative JSON file path to be used.
+      #   - [#call] A proc that can devise dynamically the relative file path from the base directory:
+      #     - Param base_dir [String] The base directory from which the JSON file is searched.
+      #     - Return [String] The corresponding relative JSON file path from base_dir.
+      def self.include_for(calling_class, cline_json_file_def)
+        calling_class.class_eval do
+          include Dir
+          include File
+          include ClineData
+
+          class << self
+            # @return [String] The relative JSON file path
+            attr_accessor :cline_json_file_def
+          end
+        end
+        calling_class.cline_json_file_def = cline_json_file_def
+      end
+
+      # Hook used when this mixin is included in a base class
+      #
+      # @param base [Class] The base class
+      def self.included(base)
+        base.extend(ClassMethods)
+      end
+    end
+  end
+end

data/lib/cline/serializable/dir.rb

@@ -0,0 +1,81 @@
+require 'fileutils'
+
+module Cline
+  module Serializable
+    # Add features to initialize from and save an object to a directory.
+    #
+    # Provides:
+    # - `.open(dir) -> [Object, nil]` Provides a new instance initialized from the directory, or nil if no directory.
+    # - `#dir -> [String]` The directory from which this object was initialized.
+    # - `#subpath(path) -> [String]` Provide a sub-path from the directory the object was initialized from.
+    module Dir
+      # Class methods that should be made accessible to any class including our mixin
+      module ClassMethods
+        # @!group Public API
+
+        # Instantiate an instance of the including class from a given directory.
+        #
+        # @param dir [String] Directory used to initialize the new instance
+        # @param args [Array] Extra parameters to give to the instance's constructor
+        # @param create [Boolean] Should the directory be created if it does not exist?
+        # @param kwargs [Hash] Extra kwargs to give to the instance's constructor
+        # @return [Object, nil] The instance initialized from this directory, or nil if none
+        def open(dir, *args, create: false, **kwargs)
+          unless ::File.exist?(dir) && ::File.directory?(dir)
+            return unless create
+
+            FileUtils.mkdir_p dir
+          end
+          instance = new_instance(dir, *args, **kwargs)
+          instance.initialize_from_dir(dir, create:)
+          instance
+        end
+
+        # @!group Internal
+
+        # Default factory for instances.
+        # This could be overriden by some classes that need to instantiate differently.
+        #
+        # @param _dir [String] The directory to create the instance for.
+        # @param args [Array] Extra parameters to give to the instance's constructor.
+        # @param kwargs [Hash] Extra kwargs to give to the instance's constructor.
+        # @return [Object] A new instance.
+        def new_instance(_dir, *args, **kwargs)
+          new(*args, **kwargs)
+        end
+      end
+
+      # @!group Internal
+
+      # Hook used when this mixin is included in a base class
+      #
+      # @param base [Class] The base class
+      def self.included(base)
+        base.extend(ClassMethods)
+      end
+
+      # @return [String] The directory used for the object's initialization
+      attr_reader :dir
+
+      # @return [Boolean] Should data be created if it does not exist?
+      attr_reader :create
+
+      # Initialize this instance from a directory
+      #
+      # @param dir [String] The directory to be used to initialize this instance
+      # @param create [Boolean] Should data be created if it does not exist?
+      def initialize_from_dir(dir, create:)
+        @dir = dir
+        @create = create
+      end
+
+      # Return the path to a sub-path of our instance directory
+      #
+      # @param path [String] The relative sub-path
+      # @return [String] The full path to the sub-path
+      def subpath(path)
+        ::File.join(dir, path)
+      end
+    end
+  end
+end

data/lib/cline/serializable/file.rb

@@ -0,0 +1,106 @@
+require 'fileutils'
+
+module Cline
+  module Serializable
+    # Add features to initialize from and save an object to a file.
+    #
+    # Provides:
+    # - `.open(file) -> [Object, nil]` Provides a new instance initialized from the file, or nil if no file.
+    # - `.monitor_file_changes(file, on_change)` Provides a monitor to be notified on file changes.
+    # - `.monitor_updates(file, on_change)` Provides a monitor to be notified on new instances upon updates.
+    # - `#file -> [String]` The file from which this object was initialized.
+    module File
+      # @!group Internal
+
+      # Class methods that should be made accessible to any class including our mixin
+      module ClassMethods
+        # Instantiate an instance of the including class from a given file.
+        #
+        # @param file [String] File path used to initialize the new instance
+        # @param args [Array] Extra parameters to give to the instance's constructor
+        # @param default [String, nil] Default file content to be created, or nil to only read existing one
+        # @param kwargs [Hash] Extra kwargs to give to the instance's constructor
+        # @return [Object, nil] The instance, or nil if no file exists
+        def open(file, *args, default: nil, **kwargs)
+          unless ::File.exist?(file)
+            return unless default
+
+            FileUtils.mkdir_p(::File.dirname(file))
+            ::File.write(file, default)
+          end
+
+          instance = new_instance(file, *args, **kwargs)
+          instance.initialize_from_file(file)
+          instance
+        end
+
+        # Monitor changes done on the file and call a callback for each update.
+        #
+        # @param file [String] File path to be monitored
+        # @param on_change [#call] Block called each time there is an update.
+        #   * Param mtime [Time, nil] New file modification time, or nil if no file
+        # @param monitoring_interval_secs [Float] The monitoring interval in seconds
+        # @yield Optional code called while monitoring is in place.
+        #   If used then monitoring is stopped at the end of the block's execution.
+        # @return [Utils::FileMonitor, nil] If no block has been given, return the monitor that needs to be
+        #   stopped by the caller when monitoring should end.
+        def monitor_file_changes(file, on_change:, monitoring_interval_secs: 1, &)
+          monitor = Utils::FileMonitor.new(file, on_change:, monitoring_interval_secs:)
+          monitor.start(&)
+          monitor unless block_given?
+        end
+
+        # Monitor changes and call a callback for each update on the updated instance.
+        #
+        # @param file [String] File path to be monitored
+        # @param args [Array] Extra parameters to give to the instance's constructor
+        # @param on_change [#call] Block called each time there is an update.
+        #   * Param instance [Object, nil] New instance with updates, or nil if no instance
+        # @param monitoring_interval_secs [Float] The monitoring interval in seconds
+        # @param kwargs [Hash] Extra kwargs to give to the instance's constructor
+        # @yield Optional code called while monitoring is in place.
+        #   If used then monitoring is stopped at the end of the block's execution.
+        # @return [Utils::FileMonitor, nil] If no block has been given, return the monitor that needs to be
+        #   stopped by the caller when monitoring should end.
+        def monitor_updates(file, *args, on_change:, monitoring_interval_secs: 1, **kwargs, &)
+          monitor_file_changes(
+            file,
+            on_change: proc do |_mtime|
+              on_change.call(self.open(file, *args, default: nil, **kwargs))
+            end,
+            monitoring_interval_secs:,
+            &
+          )
+        end
+
+        # Default factory for instances.
+        # This could be overriden by some classes that need to instantiate differently.
+        #
+        # @param _file [String] File to initialize from.
+        # @param args [Array] Extra parameters to give to the instance's constructor.
+        # @param kwargs [Hash] Extra kwargs to give to the instance's constructor.
+        # @return [Object] A new instance.
+        def new_instance(_file, *args, **kwargs)
+          new(*args, **kwargs)
+        end
+      end
+
+      # Hook used when this mixin is included in a base class
+      #
+      # @param base [Class] The base class
+      def self.included(base)
+        base.extend(ClassMethods)
+      end
+
+      # @return [String] The file used for the object's initialization
+      attr_reader :file
+
+      # Initialize this instance from a file
+      #
+      # @param file [String] The file to be used to initialize this instance
+      def initialize_from_file(file)
+        @file = file
+      end
+    end
+  end
+end