cline-rb 1.0.0

data/lib/cline/log.rb

@@ -0,0 +1,288 @@
+module Cline
+  # Cline Log entry
+  class Log < Schema
+    # @!group Public API
+
+    # Cause of an API call error
+    class ErrorCause < Schema
+      # @!group Public API
+
+      # @return [String, nil] Error code (e.g. "ConnectionRefused")
+      attribute :code, :string
+
+      # @return [String, nil] URL path that caused the error
+      attribute :path, :string
+
+      # @return [Integer, nil] Error number
+      attribute :errno, :integer
+    end
+
+    # Individual API call error (used in errors[], aggregateErrors[], and lastError)
+    class ApiError < Schema
+      # @!group Public API
+
+      # @return [String, nil] Error type identifier
+      attribute :type, :string
+
+      # @return [String, nil] Human-readable error message
+      attribute :message, :string
+
+      # @return [String, nil] Error stack trace
+      attribute :stack, :string
+
+      # @return [String, nil] Error class name (e.g. "AI_APICallError")
+      attribute :name, :string
+
+      # @return [String, nil] API endpoint URL
+      attribute :url, :string
+
+      # @return [Boolean, nil] Whether the request is retryable
+      attribute :is_retryable, :boolean
+
+      # @return [ErrorCause, nil] Underlying cause of the error
+      attribute :cause, ErrorCause
+    end
+
+    # Top-level error wrapper (the err field in error logs)
+    class Error < Schema
+      # @!group Public API
+
+      # @return [String, nil] Error type identifier
+      attribute :type, :string
+
+      # @return [String, nil] Human-readable error message
+      attribute :message, :string
+
+      # @return [String, nil] Error stack trace
+      attribute :stack, :string
+
+      # @return [String, nil] Error class name (e.g. "AI_RetryError")
+      attribute :name, :string
+
+      # @return [String, nil] Reason for the error (e.g. "maxRetriesExceeded")
+      attribute :reason, :string
+
+      # @return [Array<ApiError>, nil] Individual errors in a retry chain
+      attribute :errors, Utils::Schema.collection(ApiError)
+
+      # @return [Array<ApiError>, nil] Aggregate errors from retry attempts
+      attribute :aggregate_errors, Utils::Schema.collection(ApiError)
+
+      # @return [ApiError, nil] Last error in a retry chain
+      attribute :last_error, ApiError
+    end
+
+    # Event-specific properties for telemetry entries
+    class Properties < Schema
+      # @!group Public API
+
+      # @return [String, nil] Unique identifier for tasks and sessions
+      attribute :ulid, :string
+
+      # @return [String, nil] API provider name (e.g. "cline")
+      attribute :api_provider, :string
+
+      # @return [String, nil] Agent identifier
+      attribute :agent_id, :string
+
+      # @return [String, nil] Agent kind (e.g. "team_lead")
+      attribute :agent_kind, :string
+
+      # @return [String, nil] Conversation identifier
+      attribute :conversation_id, :string
+
+      # @return [Boolean, nil] Whether this is a subagent
+      attribute :is_subagent, :boolean
+
+      # @return [String, nil] Team identifier
+      attribute :team_id, :string
+
+      # @return [String, nil] Team name
+      attribute :team_name, :string
+
+      # @return [String, nil] Team role (e.g. "lead")
+      attribute :team_role, :string
+
+      # @return [String, nil] Lead agent identifier for teams
+      attribute :lead_agent_id, :string
+
+      # @return [String, nil] Model provider (e.g. "cline")
+      attribute :provider, :string
+
+      # @return [String, nil] Model identifier (e.g. "deepseek/deepseek-v4-flash")
+      attribute :model_id, :string
+
+      # @return [String, nil] Model name (e.g. "deepseek/deepseek-v4-flash")
+      attribute :model, :string
+
+      # @return [String, nil] Source of the conversation turn (e.g. "user", "assistant")
+      attribute :source, :string
+
+      # @return [String, nil] Mode of operation (e.g. "act")
+      attribute :mode, :string
+
+      # @return [String, nil] Timestamp in ISO 8601 format
+      attribute :timestamp, :string
+
+      # @return [String, nil] Run identifier for agent runs
+      attribute :run_id, :string
+
+      # @return [String, nil] Status of a run or task (e.g. "running", "completed")
+      attribute :status, :string
+
+      # @return [Integer, nil] Iteration number
+      attribute :iteration, :integer
+
+      # @return [String, nil] Event type (e.g. "run-started", "turn-started")
+      attribute :event_type, :string
+
+      # @return [String, nil] Session identifier
+      attribute :session_id, :string
+
+      # @return [Boolean, nil] Whether tools are enabled
+      attribute :enable_tools, :boolean
+
+      # @return [Boolean, nil] Whether spawn agent is enabled
+      attribute :enable_spawn_agent, :boolean
+
+      # @return [Boolean, nil] Whether agent teams are enabled
+      attribute :enable_agent_teams, :boolean
+
+      # @return [Integer, nil] Input tokens count
+      attribute :tokens_in, :integer
+
+      # @return [Integer, nil] Output tokens count
+      attribute :tokens_out, :integer
+
+      # @return [Float, nil] Total cost of the API call
+      attribute :total_cost, :float
+
+      # @return [Integer, nil] Cache read tokens count
+      attribute :cache_read_tokens, :integer
+
+      # @return [Integer, nil] Cache write tokens count
+      attribute :cache_write_tokens, :integer
+
+      # @return [String, nil] Tool name used (e.g. "ask_question", "run_commands")
+      attribute :tool, :string
+
+      # @return [Boolean, nil] Whether the tool use was successful
+      attribute :success, :boolean
+
+      # @return [Integer, nil] Duration in milliseconds
+      attribute :duration_ms, :integer
+
+      # @return [String, nil] Provider identifier
+      attribute :provider_id, :string
+
+      # Workspace initialization properties
+
+      # @return [Integer, nil] Number of workspace roots
+      attribute :root_count, :integer
+
+      # @return [Array<String>, nil] VCS types (e.g. ["git"])
+      attribute :vcs_types, Utils::Schema.collection(:string)
+
+      # @return [Boolean, nil] Whether the workspace has multiple roots
+      attribute :is_multi_root, :boolean
+
+      # @return [Boolean, nil] Whether the workspace has git
+      attribute :has_git, :boolean
+
+      # @return [Boolean, nil] Whether the workspace has mercurial
+      attribute :has_mercurial, :boolean
+
+      # @return [Float, nil] Initialization duration in milliseconds
+      attribute :init_duration_ms, :float
+
+      # @return [Boolean, nil] Whether feature flags are enabled
+      attribute :feature_flag_enabled, :boolean
+
+      # @return [String, nil] Extension version (e.g. "3.0.7")
+      attribute :extension_version, :string
+
+      # @return [String, nil] Cline type (e.g. "cli")
+      attribute :cline_type, :string
+
+      # @return [String, nil] Platform name (e.g. "cline")
+      attribute :platform, :string
+
+      # @return [String, nil] Platform version (e.g. "v24.3.0")
+      attribute :platform_version, :string
+
+      # @return [String, nil] Operating system type (e.g. "win32")
+      attribute :os_type, :string
+
+      # @return [String, nil] Operating system version (e.g. "Windows 11 Pro")
+      attribute :os_version, :string
+
+      # @return [String, nil] Distinct identifier
+      attribute :distinct_id, :string
+
+      # @return [String, nil] Whether the session was restored from persistence
+      attribute :restored_from_persistence, :boolean
+
+      # All attributes are already snake case
+      cline_snake_attributes(*attributes.keys)
+    end
+
+    # @!group Public API
+
+    # @return [Integer] Log level number (e.g. 30 for info, 40 for warn)
+    attribute :level, :integer
+
+    # @return [String] Timestamp in ISO 8601 format
+    attribute :time, :string
+
+    # @return [Integer] Process ID
+    attribute :pid, :integer
+
+    # @return [String] Hostname of the machine
+    attribute :hostname, :string
+
+    # @return [String] Logger name (e.g. "cline.cli")
+    attribute :name, :string
+
+    # @return [String] Component name (e.g. "main")
+    attribute :component, :string
+
+    # @return [String] Log message
+    attribute :msg, :string
+
+    # @return [Boolean, nil] Whether the session is interactive
+    attribute :interactive, :boolean
+
+    # @return [Boolean, nil] Whether a prompt is present
+    attribute :has_prompt, :boolean
+
+    # @return [String, nil] Current working directory
+    attribute :cwd, :string
+
+    # @return [String, nil] Reason for a fallback or decision
+    attribute :reason, :string
+
+    # @return [String, nil] Backend routing mode (e.g. "env-managed", "auto")
+    attribute :backend_mode, :string
+
+    # @return [Boolean, nil] Whether the local backend is forced
+    attribute :force_local_backend, :boolean
+
+    # @return [String, nil] Telemetry sink name (e.g. "TelemetryLoggerSink")
+    attribute :telemetry_sink, :string
+
+    # @return [String, nil] Event name for telemetry entries (e.g. "workspace.initialized")
+    attribute :event, :string
+
+    # @return [Properties, nil] Event-specific properties for telemetry entries
+    attribute :properties, Properties
+
+    # @return [String, nil] Severity level for error/warn logs (e.g. "error", "warn")
+    attribute :severity, :string
+
+    # @return [String, nil] Provider identifier (e.g. "cline")
+    attribute :provider_id, :string
+
+    # @return [Error, nil] Error details for error logs
+    attribute :err, Error
+  end
+end

data/lib/cline/logs.rb

@@ -0,0 +1,136 @@
+require 'forwardable'
+require 'json'
+
+module Cline
+  # Cline Logs file content
+  class Logs
+    extend Forwardable
+    include Serializable::File
+
+    # @!group Public API
+
+    # Fetch logs
+    #
+    # @param from [Time, String, nil] The horizon (exclusive) from which we select lines. Can be one of:
+    #   - [Time] The timestamp to get lines from
+    #   - [String] The exact log line to start after
+    #   - [nil] Get all log lines
+    # @return [Array<Log>] Logs list
+    def logs(from: nil)
+      logs_lines_from(from).map { |line| line.start_with?('{') ? Log.of_hash(JSON.parse(line)) : line }
+    end
+
+    # Delegates enumerating methods to the internal logs
+    def_delegators :logs, *%i[[] each empty? first last size]
+
+    # Add a new log line to the logs
+    #
+    # @param line [Log, String] The log entry to add (either a Log object or a raw string)
+    # @return [Logs] self
+    def <<(line)
+      logs_lines << (
+        if line.is_a?(Log)
+          line.to_cline_json
+        elsif line.is_a?(Hash)
+          Log.cast(line).to_cline_json
+        else
+          line
+        end
+      )
+      self
+    end
+
+    # Save the logs lines to the file
+    def save
+      raise 'This instance has not been initialized from a file' unless file
+
+      FileUtils.mkdir_p(::File.dirname(file))
+      ::File.write(file, logs_lines.map { |line| "#{line}\n" }.join)
+    end
+
+    # Monitor logs with a callback called when new or updated logs arrive
+    #
+    # @param on_log [#call] Block called each time there is a new log.
+    #   * Param log [Log, String] Log that has happened, either as a Log object or as a String if it is not JSON.
+    #   * Param last [Boolean] Is this the last log fetched from the logs?
+    # @param from [Time, String, nil] The horizon (exclusive) from which we select lines (see #logs)
+    # @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 [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(on_log:, from: nil, monitoring_interval_secs: 1, &)
+      # Keep the last log line that we have read
+      last_log = from
+      Logs.monitor_file_changes(
+        file,
+        on_change: proc do |_mtime|
+          refresh!
+          new_lines = logs_lines_from(last_log)
+          unless new_lines.empty?
+            last_idx = new_lines.size - 1
+            new_lines.each.with_index do |line, idx|
+              on_log.call(line.start_with?('{') ? Log.of_hash(JSON.parse(line)) : line, idx == last_idx)
+            end
+            last_log = new_lines.last
+          end
+        end,
+        monitoring_interval_secs:,
+        &
+      )
+    end
+
+    # Clear the cache in case the log file has changed
+    def refresh!
+      @logs_lines = nil
+    end
+
+    # Equality check
+    #
+    # @param other [Object] The other to check equality with
+    # @return [Boolean] True if objects are equal
+    def ==(other)
+      other.is_a?(Logs) &&
+        other.logs_lines == logs_lines
+    end
+
+    protected
+
+    # Get the logs lines
+    #
+    # @return [Array<String>] Logs lines
+    def logs_lines
+      @logs_lines ||= Utils::File.safe_read(file).split("\n")
+    end
+
+    private
+
+    # @!group Internal
+
+    # The regexp used to match string timestamps from log lines
+    LOG_ENTRY_TIME_REGEXP = /"time":"(\d\d\d\d-\d\d-\d\dT\d\d:\d\d:\d\d\.\d\d\dZ)"/
+    private_constant :LOG_ENTRY_TIME_REGEXP
+
+    # Get the logs lines from a given time or line
+    #
+    # @param from [Time, String, nil] The horizon (exclusive) from which we select lines (see #logs)
+    # @return [Array<String>] Selected logs lines
+    def logs_lines_from(from = nil)
+      if from
+        found_reverse_idx =
+          if from.is_a?(String)
+            logs_lines.reverse_each.find_index(from)
+          else
+            horizon = from.utc.strftime('%FT%T.%LZ')
+            logs_lines.reverse_each.find_index do |line|
+              match = line.match(LOG_ENTRY_TIME_REGEXP)
+              !match.nil? && match[1] <= horizon
+            end
+          end
+        found_reverse_idx ? logs_lines[(logs_lines.size - found_reverse_idx)..] : logs_lines
+      else
+        logs_lines
+      end
+    end
+  end
+end

data/lib/cline/mcp_settings.rb

@@ -0,0 +1,30 @@
+module Cline
+  # MCP settings
+  class McpSettings < Schema
+    # @!group Public API
+    Serializable::ClineData.include_for(self, 'settings/cline_mcp_settings.json')
+
+    # Settings associated to 1 MCP server
+    class McpServer < Schema
+      # @!group Public API
+
+      # @return [Array<String>] List of tools that are automatically approved for this server
+      attribute :auto_approve, Utils::Schema.collection(:string)
+
+      # @return [Boolean] Flag indicating if this server is disabled
+      attribute :disabled, :boolean
+
+      # @return [Integer] Server timeout in seconds
+      attribute :timeout, :integer
+
+      # @return [String] Server connection type (e.g. "sse", "stdio")
+      attribute :type, :string
+
+      # @return [String] Server URL for SSE connections
+      attribute :url, :string
+    end
+
+    # @return [Hash] Set of MCP servers settings
+    attribute :mcp_servers, Utils::Schema.map(McpServer)
+  end
+end

data/lib/cline/model.rb

@@ -0,0 +1,47 @@
+module Cline
+  # Cline model information
+  class Model < Schema
+    # @!group Public API
+
+    # @return [String] Model display name
+    attribute :name, :string
+
+    # @return [Integer] Maximum tokens output for this model
+    attribute :max_tokens, :integer
+
+    # @return [Integer] Context window size in tokens
+    attribute :context_window, :integer
+
+    # @return [Boolean] True if this model supports image inputs
+    attribute :supports_images, :boolean
+
+    # @return [Boolean] True if this model supports prompt caching
+    attribute :supports_prompt_cache, :boolean
+
+    # @return [Float] Input price per million tokens
+    attribute :input_price, :float
+
+    # @return [Float] Output price per million tokens
+    attribute :output_price, :float
+
+    # @return [Float, nil] Cache reads price per million tokens
+    attribute :cache_reads_price, :float
+
+    # @return [Float, nil] Cache writes price per million tokens
+    attribute :cache_writes_price, :float
+
+    # @return [String, nil] Model description
+    attribute :description, :string
+
+    # Thinking configuration for this model
+    class ThinkingConfig < Schema
+      # @!group Public API
+
+      # @return [Integer] Maximum thinking budget in tokens
+      attribute :max_budget, :integer
+    end
+
+    # @return [ThinkingConfig, nil] Thinking configuration
+    attribute :thinking_config, ThinkingConfig
+  end
+end

data/lib/cline/models.rb

@@ -0,0 +1,11 @@
+module Cline
+  # Base class, dynamically defined
+  ModelMap = Utils::Schema.map(Model)
+
+  # Access cached Cline models
+  class Models < ModelMap
+    # @!group Public API
+
+    Serializable::ClineData.include_for(self, 'cache/cline_models.json')
+  end
+end

data/lib/cline/overlay_hash.rb

@@ -0,0 +1,125 @@
+require 'forwardable'
+
+module Cline
+  # Class merging several Hash-like objects to give a uniform view of them through another Hash-like interface.
+  # This is used to provide unifide representations of objects present in both project and global configs.
+  # Write operations are performed on the top layer only.
+  class OverlayHash
+    extend Forwardable
+
+    # @!group Public API
+
+    include Enumerable
+
+    # Loop over all elements.
+    #
+    # @yield Optional code called for each key and value.
+    # @yieldparam key [Object] The key being iterated on.
+    # @yieldparam value [Object] The value being iterated on.
+    # @return [Enumerator] The enumerator if no block is given.
+    def each
+      return enum_for(:each) unless block_given?
+
+      seen = {}
+      @layers.each do |layer|
+        layer.each do |key, value|
+          next if seen.key?(key)
+
+          seen[key] = true
+          yield key, value
+        end
+      end
+    end
+
+    # Retrieve the value for a given key from the first layer that contains it.
+    #
+    # @param key [Object] The key to look up.
+    # @return [Object, nil] The value associated with the key, or +nil+ if not found in any layer.
+    def [](key)
+      @layers.each do |layer|
+        return layer[key] if layer.key?(key)
+      end
+      nil
+    end
+
+    # Check whether the given key exists in any layer.
+    #
+    # @param key [Object] The key to check for.
+    # @return [Boolean] +true+ if the key is present in at least one layer, +false+ otherwise.
+    def key?(key)
+      @layers.any? { |layer| layer.key?(key) }
+    end
+
+    # Return all unique keys across all layers, in priority order.
+    #
+    # @return [Array<Object>] The list of unique keys.
+    def keys
+      map { |k, _v| k }
+    end
+
+    # Return all values across all layers, in priority order.
+    #
+    # @return [Array<Object>] The list of values corresponding to the unique keys.
+    def values
+      map { |_k, v| v }
+    end
+
+    # Return the number of unique keys across all layers.
+    #
+    # @return [Integer] The total count of unique keys.
+    def size
+      keys.size
+    end
+
+    # Check whether the overlay hash contains any entries.
+    #
+    # @return [Boolean] +true+ if there are no entries across all layers, +false+ otherwise.
+    def empty?
+      none?
+    end
+
+    # Convert the overlay hash into a plain Ruby Hash.
+    #
+    # @return [Hash] A new hash containing all unique key-value pairs in priority order.
+    def to_h
+      each_with_object({}) do |(key, value), h|
+        h[key] = value
+      end
+    end
+
+    # Equality check
+    #
+    # @param other [Object] The other to check equality with
+    # @return [Boolean] True if objects are equal
+    def ==(other)
+      other.is_a?(OverlayHash) &&
+        other.layers == layers
+    end
+
+    # Delegate all write and singleton operations to the first layer
+    def_delegators :first_layer, *%i[dir new]
+
+    # @!group Internal
+
+    # Constructor
+    #
+    # @param layers [Array] List of Hash-like objects that should be served.
+    #   In case of conflicting keys, the first ones in the list get priority.
+    #   Write operations are performed on the first one only.
+    def initialize(*layers)
+      @layers = layers
+    end
+
+    protected
+
+    # @return [Array<Object>] The list of layers
+    attr_reader :layers
+
+    private
+
+    # @return [Object] First layer
+    def first_layer
+      @layers.first
+    end
+  end
+end

data/lib/cline/providers.rb

@@ -0,0 +1,59 @@
+module Cline
+  # Providers configuration stored in settings/providers.json
+  class Providers < Schema
+    # @!group Public API
+
+    Serializable::ClineData.include_for(self, 'settings/providers.json')
+
+    # A provider entry with settings, update timestamp and token source
+    class ProviderEntry < Schema
+      # @!group Public API
+
+      # Settings for a single provider entry
+      class ProviderSettings < Schema
+        # @!group Public API
+
+        # Settings specific to a provider's reasoning configuration
+        class ReasoningSettings < Schema
+          # @!group Public API
+
+          # @return [Boolean] Whether reasoning is enabled
+          attribute :enabled, :boolean
+
+          # @return [String] The reasoning effort level (e.g. "xhigh")
+          attribute :effort, :string
+        end
+
+        # @return [String] The provider name
+        attribute :provider, :string
+
+        # @return [SecretString, nil] The API key for this provider
+        attribute :api_key, SecretString
+
+        # @return [String] The model identifier
+        attribute :model, :string
+
+        # @return [ReasoningSettings, nil] Optional reasoning configuration
+        attribute :reasoning, ReasoningSettings
+      end
+
+      # @return [ProviderSettings] The provider settings
+      attribute :settings, ProviderSettings
+
+      # @return [String] The timestamp when this provider was last updated
+      attribute :updated_at, :string
+
+      # @return [String] The token source (e.g. "manual")
+      attribute :token_source, :string
+    end
+
+    # @return [Integer] The version of the providers configuration
+    attribute :version, :integer
+
+    # @return [String] The last used provider identifier
+    attribute :last_used_provider, :string
+
+    # @return [Hash] The map of provider entries keyed by provider name
+    attribute :providers, Utils::Schema.map(ProviderEntry)
+  end
+end