capistrano-ops 1.0.11 → 1.2.0

data/lib/capistrano/ops/invoke/tasks/invoke.rake

@@ -6,7 +6,7 @@ namespace :invoke do
 
   desc 'Execute a rake task on a remote server (cap invoke:rake TASK=db:migrate)'
   task :rake do
-    task_name = ENV['TASK']
+    task_name = ENV.fetch('TASK', nil)
     unless task_name
       puts "\n\nFailed! You need to specify the 'TASK' parameter!",
            'Usage: cap <stage> invoke:rake TASK=your:task',

data/lib/capistrano/ops/local/helpers.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module Capistrano
+  module Ops
+    module Local
+      module Helpers
+        def scripts_dir
+          File.expand_path(fetch(:local_scripts_dir, 'scripts/local'), Dir.pwd)
+        end
+
+        def available_scripts
+          Dir.glob(File.join(scripts_dir, '*.rb')).map { |f| File.basename(f) }.sort
+        end
+
+        def resolve_script(name)
+          return nil if name.nil? || name.empty?
+
+          candidates = [name, "#{name}.rb"].map { |n| File.join(scripts_dir, n) }
+          candidates.find { |p| File.exist?(p) }
+        end
+
+        def print_available_scripts
+          scripts = available_scripts
+          if scripts.empty?
+            puts "  (no scripts found in #{fetch(:local_scripts_dir, 'scripts/local')}/)"
+          else
+            scripts.each { |s| puts "  • #{s}" }
+          end
+        end
+
+        def abort_script_not_given(command)
+          puts "\n#{color('Usage:', :bold)} cap <stage> local:#{command} SCRIPT=<filename>"
+          puts "\n#{color('Available scripts:', :bold)}"
+          print_available_scripts
+          abort
+        end
+
+        def abort_script_not_found(name)
+          puts "\n#{color("Script not found: #{name}", :red)}"
+          puts "\n#{color('Available scripts:', :bold)}"
+          print_available_scripts
+          abort
+        end
+
+        def confirm_dangerous_stage!(action)
+          stage = fetch(:stage).to_s
+          dangerous = fetch(:local_dangerous_stages, %w[production])
+          return unless dangerous.include?(stage)
+
+          print "\n#{color("⚠  #{action} on #{stage.upcase}. Continue? [y/N] ", :yellow)}"
+          abort 'Aborted.' unless $stdin.gets.to_s.strip.casecmp('y').zero?
+        end
+
+        def remote_tmp_path(script_path)
+          "/tmp/cap_local_#{SecureRandom.hex(6)}_#{File.basename(script_path)}"
+        end
+
+        def color(text, style)
+          return text unless $stdout.tty?
+
+          code = { bold: '1', red: '31', green: '32', yellow: '33', cyan: '36', dim: '2' }[style]
+          return text unless code
+
+          "\e[#{code}m#{text}\e[0m"
+        end
+      end
+    end
+  end
+end

data/lib/capistrano/ops/local/tasks/console.rake

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+namespace :local do
+  include Capistrano::Ops::Local::Helpers
+
+  desc 'Rails console with a local script pre-loaded: cap <stage> local:console SCRIPT=<filename>'
+  task :console do
+    script = ENV.fetch('SCRIPT', nil)
+    abort_script_not_given('console') unless script
+
+    script_path = resolve_script(script)
+    abort_script_not_found(script) unless script_path
+
+    stage = fetch(:stage).to_s
+    puts "\n#{color('Script:', :bold)}  #{File.basename(script_path)}"
+    puts "#{color('Target:', :bold)}  #{stage} (interactive console)"
+
+    confirm_dangerous_stage!('Opening console')
+
+    remote_tmp = remote_tmp_path(script_path)
+    remote_irbrc = "/tmp/cap_local_irbrc_#{SecureRandom.hex(6)}.rb"
+
+    on primary(fetch(:console_role, :app)) do
+      upload! script_path, remote_tmp
+      # Wrapper loads the script into the console's main context and deletes
+      # both temp files server-side when IRB exits. The at_exit puts often
+      # gets swallowed by Sentry/etc during shutdown; the local puts in the
+      # ensure block below is what the user actually sees.
+      wrapper = <<~RUBY
+        load '#{remote_tmp}'
+        at_exit do
+          begin; File.delete('#{remote_tmp}'); rescue StandardError; end
+          begin; File.delete('#{remote_irbrc}'); rescue StandardError; end
+        end
+      RUBY
+      upload! StringIO.new(wrapper), remote_irbrc
+    end
+
+    puts "#{color("▶ Opening console with #{File.basename(script_path)} on #{stage}…", :cyan)}\n\n"
+
+    begin
+      run_interactively primary(fetch(:console_role, :app)), shell: fetch(:console_shell, nil) do
+        within current_path do
+          as user: fetch(:console_user, nil) do
+            args = ['-e', fetch(:console_env, fetch(:rails_env, fetch(:stage)))]
+            args.push('--', '-r', remote_irbrc)
+            execute(:rails, :console, *args)
+          end
+        end
+      end
+    ensure
+      # Local puts — no `on {}` block, since Capistrano's Configuration is not
+      # safely Marshal-dumpable after run_interactively (fails with
+      # "no _dump_data is defined for class Thread::Mutex"). Server-side
+      # cleanup is handled by the wrapper's at_exit hook.
+      puts color("\n\u{1F9F9} Console closed on #{stage} — server temp files cleaned up on exit.", :dim)
+    end
+  end
+end

data/lib/capistrano/ops/local/tasks/run.rake

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+namespace :local do
+  include Capistrano::Ops::Local::Helpers
+
+  desc 'Run a local script on remote via rails runner: cap <stage> local:run SCRIPT=<filename>'
+  task :run do
+    script = ENV.fetch('SCRIPT', nil)
+    abort_script_not_given('run') unless script
+
+    script_path = resolve_script(script)
+    abort_script_not_found(script) unless script_path
+
+    stage = fetch(:stage).to_s
+    puts "\n#{color('Script:', :bold)}  #{File.basename(script_path)}"
+    puts "#{color('Target:', :bold)}  #{stage}"
+
+    confirm_dangerous_stage!('Running script')
+
+    on roles(fetch(:console_role, :app)) do
+      remote_tmp = remote_tmp_path(script_path)
+
+      begin
+        upload! script_path, remote_tmp
+        puts "#{color("▶ Running #{File.basename(script_path)} on #{stage}…", :cyan)}\n\n"
+
+        within current_path do
+          with rails_env: fetch(:console_env, fetch(:rails_env, fetch(:stage))) do
+            execute :bundle, :exec, :rails, 'runner', remote_tmp
+          end
+        end
+      ensure
+        execute :rm, '-f', remote_tmp
+        puts color("\u{1F9F9} Cleaned up temp file on server", :dim)
+      end
+    end
+
+    puts "\n#{color('✔ Done.', :green)}"
+  end
+end

data/lib/capistrano/ops/local.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+require 'capistrano/ops/task_loader'
+require 'capistrano/ops/local/helpers'
+
+TaskLoader.load_tasks_if_gem_present(
+  'capistrano-rails', 'local/tasks',
+  'WARNING: Gemfile does not include capistrano-rails gem which is required for local:console (provides capistrano/rails/console)'
+)

data/lib/capistrano/ops/logrotate/paths.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'pathname'
 
 module Capistrano

data/lib/capistrano/ops/logrotate/tasks/disable.rake

@@ -3,6 +3,7 @@
 namespace :logrotate do
   include Capistrano::Ops::Logrotate::Paths
   include Capistrano::Ops::Logrotate::Helpers
+
   desc 'disable logrotate'
   task :disable do
     on roles(:app) do

data/lib/capistrano/ops/logrotate.rb

@@ -4,4 +4,5 @@ require 'capistrano/ops/task_loader'
 require 'capistrano/ops/logrotate/helpers'
 require 'capistrano/ops/logrotate/paths'
 
-TaskLoader.load_tasks_if_gem_present('whenever', 'logrotate/tasks', 'WARNING: Gemfile does not include whenever gem which is required for logrotate tasks')
+TaskLoader.load_tasks_if_gem_present('whenever', 'logrotate/tasks',
+                                     'WARNING: Gemfile does not include whenever gem which is required for logrotate tasks')

data/lib/capistrano/ops/rails/lib/backup/api.rb

@@ -4,7 +4,7 @@ module Backup
   class Api
     attr_accessor :backup_provider, :provider_config
 
-    def initialize(provider: ENV['BACKUP_PROVIDER'], provider_config: {})
+    def initialize(provider: ENV.fetch('BACKUP_PROVIDER', nil), provider_config: {})
       self.backup_provider = provider
       self.provider_config = provider_config
     end

data/lib/capistrano/ops/rails/lib/backup/s3.rb

@@ -12,8 +12,9 @@ module Backup
 
     attr_accessor :endpoint, :region, :access_key_id, :secret_access_key, :s3_resource, :s3_client
 
-    def initialize(endpoint: ENV['S3_BACKUP_ENDPOINT'], region: ENV['S3_BACKUP_REGION'], access_key_id: ENV['S3_BACKUP_KEY'],
-                   secret_access_key: ENV['S3_BACKUP_SECRET'])
+    def initialize(endpoint: ENV.fetch('S3_BACKUP_ENDPOINT',
+                                       nil), region: ENV.fetch('S3_BACKUP_REGION', nil), access_key_id: ENV.fetch('S3_BACKUP_KEY', nil),
+                   secret_access_key: ENV.fetch('S3_BACKUP_SECRET', nil))
       self.endpoint = endpoint
       self.region = region
       self.access_key_id = access_key_id
@@ -31,7 +32,7 @@ module Backup
 
     def upload(backup_file, key)
       begin
-        s3_resource.bucket(ENV['S3_BACKUP_BUCKET']).object(key).upload_file(backup_file)
+        s3_resource.bucket(ENV.fetch('S3_BACKUP_BUCKET', nil)).object(key).upload_file(backup_file)
       rescue Backup::Error => e
         puts "Upload failed: #{e.message}"
         raise e
@@ -49,7 +50,7 @@ module Backup
 
     # rubocop:disable Metrics/MethodLength
     def upload_file_as_stream(file_path, key)
-      bucket = ENV['S3_BACKUP_BUCKET']
+      bucket = ENV.fetch('S3_BACKUP_BUCKET', nil)
       # Calculate total size of the file to be uploaded
       total_size = File.size(file_path)
       chunk_size = calculate_chunk_size(total_size)
@@ -130,7 +131,7 @@ module Backup
     end
 
     def upload_folder_as_tar_gz_stream(folder_path, key)
-      bucket = ENV['S3_BACKUP_BUCKET']
+      bucket = ENV.fetch('S3_BACKUP_BUCKET', nil)
 
       # Calculate total size of the files to be uploaded
       total_size = calculate_total_size(folder_path)
@@ -256,7 +257,7 @@ module Backup
     end
 
     def remove_old_backups(basename, keep: 5)
-      all_items = s3_resource.bucket(ENV['S3_BACKUP_BUCKET']).objects(prefix: basename).map do |item|
+      all_items = s3_resource.bucket(ENV.fetch('S3_BACKUP_BUCKET', nil)).objects(prefix: basename).map do |item|
         { key: item.key, last_modified: item.last_modified }
       end
 
@@ -272,7 +273,7 @@ module Backup
           puts "Removing #{month} from S3"
           delete_items.each do |item_obj|
             puts "Removing #{item_obj[:key]} from S3"
-            s3_resource.bucket(ENV['S3_BACKUP_BUCKET']).object(item_obj[:key]).delete
+            s3_resource.bucket(ENV.fetch('S3_BACKUP_BUCKET', nil)).object(item_obj[:key]).delete
           end
         end
         puts 'Old months removed from S3'
@@ -286,7 +287,7 @@ module Backup
 
       current_month_delete_items.each do |item_obj|
         puts "Removing #{item_obj[:key]} from S3"
-        s3_resource.bucket(ENV['S3_BACKUP_BUCKET']).object(item_obj[:key]).delete
+        s3_resource.bucket(ENV.fetch('S3_BACKUP_BUCKET', nil)).object(item_obj[:key]).delete
       end
       puts 'Old backups removed from S3'
     rescue Backup::Error => e

data/lib/capistrano/ops/rails/lib/backup.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'capistrano/ops/rails/lib/backup/api'
 require 'capistrano/ops/rails/lib/backup/s3'
 

data/lib/capistrano/ops/rails/lib/notification/api.rb

@@ -4,7 +4,7 @@ module Notification
   class Api
     attr_accessor :notification_type, :notification_level
 
-    def initialize(notification_type: ENV['NOTIFICATION_TYPE'], notification_level: ENV['NOTIFICATION_LEVEL'])
+    def initialize(notification_type: ENV.fetch('NOTIFICATION_TYPE', nil), notification_level: ENV.fetch('NOTIFICATION_LEVEL', nil))
       self.notification_type = notification_type
       self.notification_level = notification_level || 'error'
     end

data/lib/capistrano/ops/rails/lib/notification/slack.rb

@@ -6,8 +6,8 @@ require 'json'
 module Notification
   class Slack
     def initialize
-      @slack_secret = ENV['SLACK_SECRET']
-      @slack_channel = ENV['SLACK_CHANNEL']
+      @slack_secret = ENV.fetch('SLACK_SECRET', nil)
+      @slack_channel = ENV.fetch('SLACK_CHANNEL', nil)
       @conn = Faraday.new(url: 'https://slack.com/api/') do |faraday|
         faraday.headers['Content-Type'] = 'application/json'
         faraday.headers['Authorization'] = "Bearer #{@slack_secret}"
@@ -20,8 +20,8 @@ module Notification
       begin
         res = @conn.post('chat.postMessage') do |req|
           req.body = {
-            "channel": @slack_channel,
-            "text": message
+            channel: @slack_channel,
+            text: message
           }.to_json
         end
         response = JSON.parse(res.body)

data/lib/capistrano/ops/rails/lib/notification/webhook.rb

@@ -7,18 +7,18 @@ module Notification
     require 'json'
 
     def initialize
-      @webhook_url = ENV['WEBHOOK_URL']
-      @secret = ENV['WEBHOOK_SECRET']
+      @webhook_url = ENV.fetch('WEBHOOK_URL', nil)
+      @secret = ENV.fetch('WEBHOOK_SECRET', nil)
       @conn = Faraday.new(url: @webhook_url) do |faraday|
         faraday.headers['Content-Type'] = 'application/json'
       end
     end
 
     def generate_signature(payload_body)
-      "md5=#{OpenSSL::HMAC.hexdigest('md5', ENV['WEBHOOK_SECRET'], payload_body)}"
+      "md5=#{OpenSSL::HMAC.hexdigest('md5', ENV.fetch('WEBHOOK_SECRET', nil), payload_body)}"
     end
 
-    def backup_notification(result, webhook_data, _notification_level)
+    def backup_notification(result, webhook_data, notification_level)
       return if @webhook_url.nil? || @secret.nil?
       return if result && notification_level == 'error'
 

data/lib/capistrano/ops/rails/lib/tasks/pg/dump.rake

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-require_relative './postgres_helper'
+require_relative 'postgres_helper'
 namespace :pg do
   include PostgresHelper
 
@@ -25,11 +25,11 @@ namespace :pg do
     result = system(commandlist)
 
     if ENV['BACKUP_PROVIDER'].present? && external_backup && result
-      puts "Uploading #{filename} to #{ENV['BACKUP_PROVIDER']}..."
+      puts "Uploading #{filename} to #{ENV.fetch('BACKUP_PROVIDER', nil)}..."
       provider = Backup::Api.new
       begin
         provider.upload("#{backup_path}/#{filename}", filename.to_s, 'file')
-        puts "#{filename} uploaded to #{ENV['BACKUP_PROVIDER']}"
+        puts "#{filename} uploaded to #{ENV.fetch('BACKUP_PROVIDER', nil)}"
       rescue StandardError => e
         puts "#{filename} upload failed: #{e.message}"
       end

data/lib/capistrano/ops/rails/lib/tasks/pg/postgres_helper.rb

@@ -27,7 +27,7 @@ module PostgresHelper
     messages = []
     if result
       messages << "Backup of #{database} successfully finished at #{Time.now}"
-      messages << "Backup path:\`#{backup_path}/#{filename}\`"
+      messages << "Backup path:`#{backup_path}/#{filename}`"
     else
       messages << "Backup of #{database} failed at #{Time.now}"
     end
@@ -54,14 +54,14 @@ module PostgresHelper
     commandlist = []
     commandlist << "export PGPASSWORD='#{password}'"
     commandlist << "cd #{backup_path}"
-    commandlist << "pg_dump --no-acl --no-owner #{options.join('')} > #{filename}"
+    commandlist << "pg_dump --no-acl --no-owner #{options.join} > #{filename}"
     commandlist.join(' && ')
   end
 
   def size_str(size)
     units = %w[B KB MB GB TB]
     e = (Math.log(size) / Math.log(1024)).floor
-    s = format('%.2f', size.to_f / 1024**e)
+    s = format('%.2f', size.to_f / (1024**e))
     s.sub(/\.?0*$/, units[e])
   end
 end

data/lib/capistrano/ops/rails/lib/tasks/pg/remove_old_dumps.rake

@@ -12,7 +12,7 @@ namespace :pg do
   external_backup = Rails.env.production? || ENV['EXTERNAL_BACKUP_ENABLED'] == 'true'
 
   task :remove_old_dumps do
-    bash_regex = "'#{@database}.{0,}\.dump'"
+    bash_regex = "'#{@database}.{0,}.dump'"
 
     unless backups_enabled
       puts 'remove_old_dumps: Backups are disabled'

data/lib/capistrano/ops/rails/lib/tasks/storage/backup.rake

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-require_relative './storage_helper'
+require_relative 'storage_helper'
 namespace :storage do
   include StorageHelper
 

data/lib/capistrano/ops/rails/lib/tasks/storage/remove_old_backups.rake

@@ -14,7 +14,7 @@ namespace :storage do
   @total_external_backups_no = (@env_external_no || ENV['NUMBER_OF_BACKUPS'] || 7).to_i
   desc 'remove old storage backups'
   task :remove_old_backups do
-    bash_regex = "'storage_.{0,}\.tar.gz'"
+    bash_regex = "'storage_.{0,}.tar.gz'"
 
     unless backups_enabled
       puts 'remove_old_backups: Backups are disabled'
@@ -37,7 +37,7 @@ namespace :storage do
       'xargs rm -rf'
     ]
 
-    result = system(commandlist.join(' | ')) if @total_local_backups_no.positive? && local_backup || !local_backup && external_backup
+    result = system(commandlist.join(' | ')) if (@total_local_backups_no.positive? && local_backup) || (!local_backup && external_backup)
     puts 'remove_old_backups: local cleanup finished' if result
 
     if ENV['BACKUP_PROVIDER'].present? && external_backup

data/lib/capistrano/ops/rails/lib/tasks/storage/storage_helper.rb

@@ -9,7 +9,7 @@ module StorageHelper
         backups_enabled: env_or_production('BACKUPS_ENABLED'),
         external_backup: env_or_production('EXTERNAL_BACKUP_ENABLED'),
         keep_local_backups: env_or_production('KEEP_LOCAL_STORAGE_BACKUPS'),
-        backup_provider: ENV['BACKUP_PROVIDER']
+        backup_provider: ENV.fetch('BACKUP_PROVIDER', nil)
       }
   end
 
@@ -23,7 +23,7 @@ module StorageHelper
     messages = []
     if result
       messages << "Backup of storage folder successfully finished at #{Time.now}"
-      messages << "Backup path:\`#{@backup_path}/#{@filename}\`"
+      messages << "Backup path:`#{@backup_path}/#{@filename}`"
     else
       messages << "Backup of storage folder failed at #{Time.now}"
     end
@@ -34,19 +34,19 @@ module StorageHelper
     @backup_path = settings[:backup_path]
     @date = Time.now.to_i
     @filename = "storage_#{@date}.tar.gz"
-    FileUtils.mkdir_p(@backup_path) unless Dir.exist?(@backup_path)
+    FileUtils.mkdir_p(@backup_path)
     "tar -zcf #{@backup_path}/#{@filename} -C #{settings[:storage_path]} ."
   end
 
   def size_str(size)
     units = %w[B KB MB GB TB]
     e = (Math.log(size) / Math.log(1024)).floor
-    s = format('%.2f', size.to_f / 1024**e)
+    s = format('%.2f', size.to_f / (1024**e))
     s.sub(/\.?0*$/, units[e])
   end
 
   def create_local_backup(filename, storage_path, backup_path)
-    FileUtils.mkdir_p(backup_path) unless Dir.exist?(backup_path)
+    FileUtils.mkdir_p(backup_path)
     response = system(backup_cmd(backup_path: backup_path, storage_path: storage_path))
     FileUtils.rm_rf("#{@backup_path}/#{filename}") unless response
     puts response ? "Backup created: #{backup_path}/#{@filename} (#{size_str(File.size("#{@backup_path}/#{@filename}"))})" : 'Backup failed removing dump file'

data/lib/capistrano/ops/version.rb

@@ -2,6 +2,6 @@
 
 module Capistrano
   module Ops
-    VERSION = '1.0.11'
+    VERSION = '1.2.0'
   end
 end

data/lib/capistrano/ops/whenever.rb

@@ -2,4 +2,5 @@
 
 require 'capistrano/ops/task_loader'
 
-TaskLoader.load_tasks_if_gem_present('whenever', 'whenever/tasks', 'WARNING: Gemfile does not include whenever gem which is required for whenever tasks')
+TaskLoader.load_tasks_if_gem_present('whenever', 'whenever/tasks',
+                                     'WARNING: Gemfile does not include whenever gem which is required for whenever tasks')

data/lib/capistrano/ops/wkhtmltopdf/tasks/setup.rake

@@ -2,6 +2,7 @@
 
 namespace :wkhtmltopdf do
   include Capistrano::Ops::Wkhtmltopdf::Helpers
+
   after 'deploy:symlink:release', 'wkhtmltopdf:setup'
 
   desc 'unzip wkhtmltopdf if necessary'

data/spec/capistrano/ops/local/helpers_spec.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+require 'tmpdir'
+require 'capistrano/ops/local/helpers'
+
+RSpec.describe Capistrano::Ops::Local::Helpers do
+  let(:host) do
+    Class.new do
+      include Capistrano::Ops::Local::Helpers
+
+      def initialize(scripts_dir_override)
+        @scripts_dir_override = scripts_dir_override
+      end
+
+      def fetch(key, default = nil)
+        return @scripts_dir_override if key == :local_scripts_dir
+
+        default
+      end
+    end
+  end
+
+  around do |example|
+    Dir.mktmpdir do |dir|
+      @tmp = dir
+      Dir.chdir(dir) { example.run }
+    end
+  end
+
+  def write_script(name)
+    dir = File.join(@tmp, 'ops', 'scripts')
+    FileUtils.mkdir_p(dir)
+    File.write(File.join(dir, name), '# example')
+    dir
+  end
+
+  describe '#available_scripts' do
+    it 'returns sorted basenames of .rb files' do
+      write_script('b.rb')
+      write_script('a.rb')
+      write_script('note.txt')
+
+      instance = host.new('ops/scripts')
+
+      expect(instance.available_scripts).to eq(%w[a.rb b.rb])
+    end
+
+    it 'is empty when the directory does not exist' do
+      instance = host.new('does/not/exist')
+
+      expect(instance.available_scripts).to eq([])
+    end
+  end
+
+  describe '#resolve_script' do
+    it 'returns the full path when the exact filename exists' do
+      write_script('foo.rb')
+
+      instance = host.new('ops/scripts')
+
+      expect(instance.resolve_script('foo.rb')).to end_with('/ops/scripts/foo.rb')
+    end
+
+    it 'auto-appends .rb when omitted' do
+      write_script('foo.rb')
+
+      instance = host.new('ops/scripts')
+
+      expect(instance.resolve_script('foo')).to end_with('/ops/scripts/foo.rb')
+    end
+
+    it 'returns nil for unknown names' do
+      write_script('foo.rb')
+
+      instance = host.new('ops/scripts')
+
+      expect(instance.resolve_script('bar')).to be_nil
+    end
+
+    it 'returns nil for empty input' do
+      instance = host.new('ops/scripts')
+
+      expect(instance.resolve_script(nil)).to be_nil
+      expect(instance.resolve_script('')).to be_nil
+    end
+  end
+
+  describe '#remote_tmp_path' do
+    it 'produces a unique /tmp path preserving the basename' do
+      instance = host.new('ops/scripts')
+
+      path = instance.remote_tmp_path('/some/where/foo.rb')
+
+      expect(path).to match(%r{\A/tmp/cap_local_[0-9a-f]{12}_foo\.rb\z})
+    end
+  end
+
+  describe '#color' do
+    it 'returns plain text when stdout is not a TTY' do
+      instance = host.new('ops/scripts')
+      allow($stdout).to receive(:tty?).and_return(false)
+
+      expect(instance.color('hello', :red)).to eq('hello')
+    end
+
+    it 'wraps text in ANSI escape when stdout is a TTY and style is known' do
+      instance = host.new('ops/scripts')
+      allow($stdout).to receive(:tty?).and_return(true)
+
+      expect(instance.color('hello', :red)).to eq("\e[31mhello\e[0m")
+    end
+
+    it 'passes text through unchanged for unknown styles' do
+      instance = host.new('ops/scripts')
+      allow($stdout).to receive(:tty?).and_return(true)
+
+      expect(instance.color('hello', :magenta)).to eq('hello')
+    end
+  end
+end

data/spec/capistrano/ops/version_spec.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+RSpec.describe Capistrano::Ops do
+  it 'has a version number' do
+    expect(Capistrano::Ops::VERSION).to match(/\A\d+\.\d+\.\d+\z/)
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require 'capistrano/ops/version'
+
+RSpec.configure do |config|
+  config.expect_with :rspec do |expectations|
+    expectations.include_chain_clauses_in_custom_matcher_descriptions = true
+  end
+
+  config.mock_with :rspec do |mocks|
+    mocks.verify_partial_doubles = true
+  end
+
+  config.shared_context_metadata_behavior = :apply_to_host_groups
+  config.disable_monkey_patching!
+  config.warnings = false
+  config.default_formatter = 'doc' if config.files_to_run.one?
+  config.order = :random
+  Kernel.srand config.seed
+end