cline-rb 1.0.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f2ca7f9e00479a00256f8b855bac70016da1a7a593a5912900820166f1e35d72
-  data.tar.gz: 39c24569d60b34127173ae7aac99600b89d419de0443cbd2edbc26a9c7beb509
+  metadata.gz: 61431cfcf1fb2275838e3781f564c4697ae093a2605ebd8c2dd579ce10326939
+  data.tar.gz: 1604c7050d3d0e21a8d716207f4a43311891bf9205c6372b33df43a971070821
 SHA512:
-  metadata.gz: f64d28459324a8251823c224d605c748c062932ff2dfa83006ee58b6c2b1c364fe8678f7ea5424422b0241c9d0fd375b215ebd19e929d35df7d1d95cd7047b30
-  data.tar.gz: 9e93540a9bab1f9cf19adc560057b0b8d20bb095ee6e469d112efc4ddc740f7f88eb624ce6295853bf763497d138ea6d285ee3b621edff206eab0d1d5c355e40
+  metadata.gz: d675729aaf7d8dc1c6f88164899545cc9e321c1ffcb76f3065fa19f7bffcceeb9a87f7c20de9e1612e08f38431c0b66b82d76ad7b22ab0f0cd0f522de0036063
+  data.tar.gz: 23b351b69ccdd74b03e1ced53a7330f813e8eb682051056e4e7d110957f8bc1cca08b751a6047c6b3c4a4d5d97dccf408ab21d67ba35f256031756528cc426be

data/CHANGELOG.md

@@ -1,3 +1,9 @@
+# [v1.1.0](https://github.com/Muriel-Salvan/cline-rb/compare/v1.0.0...v1.1.0) (2026-07-01 13:34:01)
+
+### Features
+
+* [[feature] feat: include CliStub spec files in gem and document usage in README](https://github.com/Muriel-Salvan/cline-rb/commit/6d8103fc559194396cd50508728625c82e8a3f19)
+
 # [v0.0.1](https://github.com/Muriel-Salvan/cline-rb/compare/...v0.0.1) (2026-07-01 12:59:01)
 
 ### Patches

data/README.md

@@ -103,6 +103,7 @@ Designed as a Ruby library (not a standalone CLI), **cline-rb** lets you build a
   - [Install dependencies](#install-dependencies)
   - [Project structure](#project-structure)
   - [Running tests](#running-tests)
+  - [Using the Cline CLI stub in other project's test cases](#using-the-cline-cli-stub-in-other-projects-test-cases)
   - [Code linting](#code-linting)
   - [Code coverage](#code-coverage)
   - [Building the gem](#building-the-gem)
@@ -1040,6 +1041,42 @@ TEST_DEBUG=1 bundle exec rspec
 
 The `.rspec` file configures `--color` and `--require spec_helper` by default.
 
+### Using the Cline CLI stub in other project's test cases
+
+The `cline-rb` gem ships with a `CliStub` class that external projects can use to mock the Cline CLI in their own unit tests. It intercepts `PTY.spawn` calls and replaces them with a lightweight stub that simulates Cline CLI behaviour (stdout, sessions, tasks, logs, exit codes, etc.).
+
+Example usage:
+
+```ruby
+require "#{Gem.loaded_specs['cline-rb'].full_gem_path}/spec/cline_test/cli_stub"
+
+it 'tests something in my project' do
+  # Setup the Cline CLI stub
+  cli_stub = ClineTest::CliStub.new
+  cli_stub.mock_commands(
+    {
+      log: {},
+      session: {
+        messages: [
+          {
+            ts: 100,
+            role: 'assistant',
+            content: [{ type: 'text', text: 'Assistant Output' }]
+          }
+        ]
+      }
+    }
+  )
+  # Run the code that would have executed the Cline CLI
+  result = Cline::Cli.new(config: '.test-config').task 'A nice user prompt'
+  expect(result[:message].content.first.text).to eq 'Assistant Output'
+  # Use the stub to check what was called
+  expect(cli_stub.issued_commands.first[:command]).to eq ['--config', '.test-config', 'A nice user prompt']
+end
+```
+
+For full API documentation of the `CliStub` class, see the [ClineTest::CliStub YARD documentation](https://www.rubydoc.info/gems/cline-rb/ClineTest/CliStub).
+
 ### Code linting
 
 The project uses **RuboCop** (~> 1.86) with `rubocop-rspec` and `rubocop-yard` plugins.

data/lib/cline/version.rb

@@ -2,5 +2,5 @@ module Cline
   # @!group Public API
 
   # Gem version
-  VERSION = '1.0.0'
+  VERSION = '1.1.0'
 end

data/spec/cline_test/cli_stub.rb

@@ -0,0 +1,209 @@
+require 'pty_compat'
+
+module ClineTest
+  # Stub of the Cline CLI (mocking calls to PTY.spawn).
+  # This can be used by external projects that need to mock or stub Cline CLI in their own unit tests.
+  class CliStub
+    class << self
+      # Capture the original PTY.spawn method in case some test cases want to use it while the real one is mocked.
+      attr_accessor :original_pty_spawn
+
+      # @return [Boolean] The debug mode.
+      attr_accessor :debug
+
+      # Log debug a message
+      #
+      # @param message [String, nil] The message to log debug, or nil if given by a proc returning the message for lazy evaluation
+      # @yield The optional code returning the message to log in case of debug
+      # @yieldreturn [String] The message to log
+      def log_debug(message = nil)
+        return unless @debug
+
+        puts "[CLINE STUB DEBUG] - #{block_given? ? yield : message}"
+      end
+    end
+    self.original_pty_spawn = ::PTY.method(:spawn)
+
+    # Constructor
+    #
+    # @param example [Object] The RSpec example for which the stub is executed
+    # @param debug [Boolean] Are we in debug mode?
+    # @param temp_dir [String] Temporary directory used to communicate with the stub
+    def initialize(example:, debug: false, temp_dir: '.cline_test/tmp')
+      @example = example
+      CliStub.debug = debug
+      @temp_dir = temp_dir
+    end
+
+    # Mock a list of commands, with their corresponding stdout, stderr and exit status.
+    # This helper hides the underlying ways of running commands from Cline::Cli.
+    # It uses a Cline CLI stub that executes mocked commands in place of the real Cline CLI.
+    #
+    # @param commands [Hash, Array] The description of the mocked behaviour the Cline CLI stub will have.
+    #   This parameter can be of 2 kinds:
+    #   - [Hash{Array<String, Regexp> => Hash{Symbol => Object}, Array<Hash{Symbol => Object}>}] Describe a list of (or a single) instructions,
+    #     for each command to mock.
+    #     The command to be mocked is the array of Cline arguments (after the cline executable).
+    #     Each argument from this command line array can be either a String for exact match or a Regexp for pattern matching.
+    #     Each mocked instruction is described below.
+    #   - [Array<Hash{Symbol => Object}, Array<Hash{Symbol => Object}>>] Describe a sequential list of groups (or single) instructions.
+    #     Each group of instruction will be executed for each new command that gets executed, regardless of its arguments.
+    #     Each mocked instruction is described below.
+    #
+    #   Each instruction is a [Hash{Symbol => Object}] that describes the behaviour to mock.
+    #   They are executed in sequence of the list they belong to, and in sequence of the keys inside each Hash.
+    #   Here is the possible instructions that are available:
+    #   - debug [Boolean] Set debug mode.
+    #   - eval [String] Execute some code.
+    #   - exit [Integer] Exit with the given exit status.
+    #   - log [Hash, String] Add a line in the Cline logs, either as a JSON Hash or a raw String.
+    #     This property should be used only with a command using the --config flag.
+    #   - session [Hash{Symbol => Object}] Create a session.
+    #     This property should be used only with a command using the --config flag.
+    #     Here is the list of all properties that can be set for the session description:
+    #     - Any attribute that is in a session JSON file.
+    #     - messages [Array<Hash{Symbol => Object}, Array<Hash{Symbol => Object}>>, nil] List of messages (or messages groups) to be created,
+    #       or nil if none.
+    #       Each message (or group) from the list will be created with 0.2 seconds interval.
+    #       If the message's text content is a Hash with an eval key, the text content is replaced by the corresponding code execution.
+    #   - sleep [Float] Sleep for a given time in seconds.
+    #   - stderr [String] Output a string to stderr.
+    #   - stdout [String] Output a string to stdout.
+    #   - task [Hash{Symbol => Object}] Create a task.
+    #     This property should be used only with a command using the --config flag.
+    #     Here is the list of all properties that can be set for the task description:
+    #     - messages [Array<Hash{Symbol => Object}, Array<Hash{Symbol => Object}>>, nil] List of messages (or messages groups) to be created,
+    #       or nil if none.
+    #       Each message (or group) from the list will be created with 0.2 seconds interval.
+    def mock_commands(commands = {})
+      temp_dir = @temp_dir
+      run_idx = 0
+      @example.instance_eval do
+        # Mock `PTY.spawn(*args) do |reader, writer, pid|` with spies pattern
+        allow(::PTY).to receive(:spawn) do |*args, &block|
+          cline_args = args[(args.find_index { |arg| arg.end_with?('cline') } + 1)..]
+          # Find the instructions corresponding to this Cline CLI run we want to mock
+          instructions =
+            if commands.is_a?(Hash)
+              # Ignore the verbose flag for command research if we activated the debug mode on purpose
+              cline_args_search = CliStub.debug ? cline_args - ['--verbose'] : cline_args
+              _mocked_command, found_instructions = commands.find do |search_command, _search_instructions|
+                search_command.size == cline_args_search.size &&
+                  search_command.zip(cline_args_search).all? { |search_arg, arg| search_arg.is_a?(Regexp) ? arg =~ search_arg : arg == search_arg }
+              end
+              found_instructions
+            else
+              commands[run_idx]
+            end
+          instructions ||= []
+          # Create the JSON file that will give all instructions to execute to our Cline CLI stub.
+          stub_conf_file = "#{temp_dir}/cli_stub.json"
+          FileUtils.mkdir_p File.dirname(stub_conf_file)
+          File.write(
+            stub_conf_file,
+            JSON.dump(
+              # Normalize instructions (always using Arrays, setting default values).
+              (
+                (@debug ? [{ debug: true }] : []) +
+                (instructions.is_a?(Array) ? instructions : [instructions])
+              ).map do |instructions_set|
+                normalized_instructions = instructions_set.dup
+                if normalized_instructions[:log].is_a?(Hash)
+                  normalized_instructions[:log] = {
+                    level: 30,
+                    hostname: 'LOCALHOST',
+                    name: 'cline.cli',
+                    component: 'main',
+                    properties: {
+                      ulid: 'test-session-id'
+                    }
+                  }.merge(normalized_instructions[:log])
+                end
+                if normalized_instructions[:session]
+                  normalized_instructions[:session] = {
+                    version: 1,
+                    session_id: 'test-session-id',
+                    source: 'cli',
+                    status: 'running',
+                    interactive: false,
+                    provider: 'cline',
+                    model: 'deepseek/deepseek-v4-flash',
+                    cwd: Dir.pwd,
+                    workspace_root: Dir.pwd,
+                    team_name: 'team-sjHpe',
+                    enable_tools: true,
+                    enable_spawn: true,
+                    enable_teams: true
+                  }.merge(normalized_instructions[:session])
+                  if normalized_instructions[:session][:messages]
+                    default_message = {
+                      id: 'msg_id_1',
+                      role: 'assistant',
+                      content: [
+                        {
+                          type: 'text',
+                          text: 'Message content'
+                        }
+                      ],
+                      ts: 100
+                    }
+                    normalized_instructions[:session][:messages] = normalized_instructions[:session][:messages].map do |messages_group|
+                      (messages_group.is_a?(Array) ? messages_group : [messages_group]).map { |message| default_message.merge(message) }
+                    end
+                  end
+                end
+                if normalized_instructions.dig(:task, :messages)
+                  default_message = { ts: 100, type: 'say', say: 'text', text: 'Message content' }
+                  normalized_instructions[:task][:messages] = normalized_instructions[:task][:messages].map do |messages_group|
+                    (messages_group.is_a?(Array) ? messages_group : [messages_group]).map { |message| default_message.merge(message) }
+                  end
+                end
+                normalized_instructions
+              end
+            )
+          )
+          # Run PTY.spawn with our stub instead of the real Cline CLI.
+          stubbed_cmd = ["ruby#{'.exe' if OS.windows?}", File.expand_path("#{__dir__}/stubs/cline")] + cline_args
+          CliStub.log_debug { "Execute `#{stubbed_cmd}` with stub conf:\n#{JSON.pretty_generate(JSON.parse(File.read(stub_conf_file)))}" }
+          # In Windows' Ruby implementation (ruby.exe) there is actually a bug that splits multiline arguments into separate arguments.
+          # This bug does not exist on Linux implementations.
+          # Because of that, we manually replace the new lines with a magic key so that the behaviour stays consistent with the real arguments
+          #   that would have been sent to Cline CLI.
+          # Our stub is then doing the opposite conversion on Windows only.
+          stubbed_cmd.map! { |arg| arg.gsub("\n", '__CLINE_STUB__NEW_LINE__') } if OS.windows?
+          result = nil
+          original_cline_stub_dir = ENV.fetch('CLINE_STUB_DIR', nil)
+          ENV['CLINE_STUB_DIR'] = temp_dir
+          begin
+            result = CliStub.original_pty_spawn.call(*stubbed_cmd) do |reader, writer, pid|
+              if @debug
+                allow(reader).to receive(:each_line).and_wrap_original do |original_each_line, &each_line_block|
+                  original_each_line.call do |line|
+                    CliStub.log_debug "[Cline stub stdout] - #{Cline::Utils::Logger.sanitize_pty_output(line)}"
+                    each_line_block.call(line)
+                  end
+                end
+              end
+              block.call(reader, writer, pid)
+            end
+          ensure
+            ENV['CLINE_STUB_DIR'] = original_cline_stub_dir
+          end
+          run_idx += 1
+          result
+        end
+      end
+    end
+
+    # Get the list of Cline CLI commands that were issued during this test run
+    #
+    # @return [Array<Hash{Symbol => Object}>] List of commands that have been issued:
+    #   * pid [Integer] The PID of the Cline process
+    #   * command [Array<String>] The command itself
+    #   * stdin [String, nil] The stdin that was redirected to this command, or nil if none
+    def issued_commands
+      calls_file = "#{@temp_dir}/cli_calls.json"
+      File.exist?(calls_file) ? JSON.parse(File.read(calls_file), symbolize_names: true) : []
+    end
+  end
+end

data/spec/cline_test/stubs/cline

@@ -0,0 +1,211 @@
+#!/usr/bin/env ruby
+
+# This is a stub of the cline command line.
+
+# It looks for its stub configuration in "#{ENV['CLINE_STUB_DIR']}/cli_stub.json".
+# The cli_stub.json file contains the attributes defined by the mock_commands method (see #ClineTest::Helpers::Cli#mock_commands).
+
+# It also records all its call arguments and stdin in the file named "#{ENV['CLINE_STUB_DIR']}/cli_calls.json".
+# Those records are appended to the file if it already exists.
+# This file contains an Array of calls information:
+# * pid [Integer] The PID of the process
+# * command [String] Command line that was called
+# * stdin [String, nil] The content of stdin, or nil if none
+
+require 'fileutils'
+require 'json'
+require 'os'
+
+cline_stub_dir = ENV.fetch('CLINE_STUB_DIR', nil)
+raise 'CLINE_STUB_DIR environment variable should be set to the directory containing the Cline stub configuration' unless cline_stub_dir
+
+# Ruby's Windows implementation splits multilines arguments.
+# Therefore we manually replaced them with a magic key.
+# Make sure they are converted back to real new lines, as it would be received by the real Cline CLI.
+ARGV.map! { |arg| arg.gsub('__CLINE_STUB__NEW_LINE__', "\n") } if OS.windows?
+
+# @return [String] The config directory
+def config_dir
+  @config_dir ||= begin
+    config_match = ARGV.join(' ').match(/--config ([^\s]+)/)[1]
+    raise 'The Cline stub can only handle this instruction if used with the --config flag' unless config_match
+
+    config_match
+  end
+end
+
+# @return [Boolean] Are we in plan mode?
+def plan_mode?
+  ARGV.include? '--plan'
+end
+
+# Return a session messages file content, for a given list of messages.
+# Always prepend the user input as a user message.
+#
+# @param session_id [String] The session id
+# @param messages [Array<Hash{Symbol => Object}>] List of messages
+# @return [Hash] The JSON messages file content
+#   If the message's text content is Hash with an eval key, the text content is replaced by the corresponding code execution.
+def session_messages(session_id, messages)
+  {
+    version: 1,
+    updated_at: Time.now.utc.strftime('%FT%T.%LZ'),
+    agent: 'lead',
+    sessionId: session_id,
+    messages: (
+      [
+        {
+          ts: 10,
+          role: 'user',
+          content: [{ type: 'text', text: "<user_input mode=\"#{plan_mode? ? 'plan' : 'act'}\">#{ARGV.last}</user_input>" }]
+        }
+      ] +
+        messages
+    ).map do |message|
+      if message[:content]
+        message.merge(
+          content: message[:content].map do |content|
+            if content[:text].is_a?(Hash) && content[:text][:eval]
+              content.merge(text: eval(content[:text][:eval]))
+            else
+              content
+            end
+          end
+        )
+      else
+        message
+      end
+    end,
+    system_prompt: 'You are Cline, an AI coding agent.'
+  }
+end
+
+# Write session messages for a given session ID
+#
+# @param session_id [String] The session ID
+# @param messages [Array<Hash>] The messages to write
+def write_session_messages(session_id, messages)
+  log_debug "[Session #{session_id}] - Write #{messages.size} messages"
+  File.write(
+    File.join(config_dir, 'data', 'sessions', session_id, "#{session_id}.messages.json"),
+    JSON.pretty_generate(session_messages(session_id, messages))
+  )
+end
+
+# Log debug a message
+#
+# @param message [String] Message to log debug
+def log_debug(message)
+  puts "[CLINE STUB DEBUG] - #{message}" if @debug
+end
+
+# Make sure output is sent directly to the calling process
+$stdout.sync = true
+$stderr.sync = true
+
+@debug = false
+
+# Record the call
+calls_file = "#{cline_stub_dir}/cli_calls.json"
+calls = File.exist?(calls_file) ? JSON.parse(File.read(calls_file)) : []
+File.write(
+  calls_file,
+  JSON.dump(
+    calls + [
+      {
+        pid: Process.pid,
+        command: ARGV,
+        stdin:
+          if $stdin.tty?
+            nil
+          else
+            stdin = $stdin.read
+            stdin.empty? ? nil : stdin
+          end
+      }
+    ]
+  )
+)
+
+# Read the config driven by mock_commands and execute all instructions in sequence
+JSON.parse(File.read("#{cline_stub_dir}/cli_stub.json"), symbolize_names: true).each do |instructions|
+  instructions.each do |name, desc|
+    log_debug "Execute instruction #{name}..."
+    case name
+    when :debug
+      @debug = desc
+    when :eval
+      eval desc
+    when :exit
+      exit desc
+    when :log
+      log_file = File.join(config_dir, 'data', 'logs', 'cline.log')
+      FileUtils.mkdir_p(File.dirname(log_file))
+      File.write(
+        log_file,
+        "#{
+          if desc.is_a?(String)
+            desc
+          else
+            # Prepare default values that are process dependent
+            JSON.dump(
+              {
+                time: Time.now.utc.strftime('%FT%T.%LZ'),
+                pid: Process.pid
+              }.merge(desc)
+            )
+          end
+        }\n",
+        mode: 'a+'
+      )
+    when :session
+      session_messages = desc.delete(:messages)
+      session_dir = File.join(config_dir, 'data', 'sessions', desc[:session_id])
+      messages_file = File.join(session_dir, "#{desc[:session_id]}.messages.json")
+      FileUtils.mkdir_p(session_dir)
+      File.write(
+        File.join(session_dir, "#{desc[:session_id]}.json"),
+        JSON.pretty_generate(
+          {
+            # Prepare default values that are process dependent
+            pid: Process.pid,
+            started_at: Time.now.utc.strftime('%FT%T.%LZ'),
+            messages_path: messages_file
+          }.merge(desc)
+        )
+      )
+      if session_messages
+        # First create empty file
+        write_session_messages(desc[:session_id], [])
+        sleep 0.2
+        # Then add test messages 1 by 1 with 0.2 seconds delay
+        session_messages.size.times do |idx|
+          write_session_messages(desc[:session_id], session_messages[0..idx].flatten(1))
+          sleep 0.2
+        end
+      end
+    when :sleep
+      sleep desc
+    when :stderr
+      $stderr.write desc
+    when :stdout
+      $stdout.write desc
+    when :task
+      # Simulate a task being created
+      $stdout.write "{\"type\":\"task_started\",\"taskId\":\"12345\"}\n"
+      task_dir = File.join(config_dir, 'data', 'tasks', '12345')
+      FileUtils.mkdir_p(task_dir)
+      if desc[:messages]
+        messages_file = File.join(task_dir, 'ui_messages.json')
+        # First create empty file
+        File.write(messages_file, '[]')
+        sleep 0.2
+        # Then add test messages 1 by 1 with 0.2 seconds delay
+        desc[:messages].size.times do |idx|
+          File.write(messages_file, JSON.dump(desc[:messages][0..idx].flatten(1)))
+          sleep 0.2
+        end
+      end
+    end
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: cline-rb
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.1.0
 platform: ruby
 authors:
 - Muriel Salvan
@@ -224,6 +224,8 @@ files:
 - lib/cline/workspace.rb
 - lib/cline/workspace_settings.rb
 - lib/cline/workspaces.rb
+- spec/cline_test/cli_stub.rb
+- spec/cline_test/stubs/cline
 homepage: https://github.com/Muriel-Salvan/cline-rb
 licenses:
 - BSD-3-Clause