capistrano-ops 1.1.0 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 708599bef12f8e7ce1b96a36fb09c1bc9acc4d50d871f2d1d5a3790240455096
-  data.tar.gz: 8c13bfc221324e6303f474453185f868d9984dba83da63de7715b747d9113594
+  metadata.gz: fe9dc820d50c226c74d26afad1f5031651bdf9758c220268cfe1d8721416b011
+  data.tar.gz: 5ac2da6ebbd2a6d7ba4bebf031b2bd3b690f30367ce48437a8c2656a2b65ec44
 SHA512:
-  metadata.gz: 3bd6ada29edf5e6a3c077c35a83908d1b40e235b0f33497a33b309e7902ea4fe16910a078e41b5bd5feb58246d4903e31b31d32567d88341ec5847c89a435aa9
-  data.tar.gz: 2d987eaaab73c8c5a6f595226371c8979d816656e3014fa744b1725bb27dff4e82cdd66d79e92dcc89fd2963dc03f5c3e6f5ede7a85c0fc33f639c7ff9e0dcfa
+  metadata.gz: de3334c09fe3b2f7cb113d13d8a309d5466464c438499e684531e015d888f73cdc8e2f7d033bbe96cf9bebab64c89ba8c18d1b74cae48ed6df5172ea47741302
+  data.tar.gz: 3d177c55f3fcf475f030f67222a0a14b715f712f4627ae6c96db27e8f75a2af162015080410d7bbd0f822b854cbfd88e5e16df668cca21132ddd4cbccd462177

data/.rubocop.yml

@@ -10,7 +10,6 @@ AllCops:
     - 'vendor/**/*'
     - 'tmp/**/*'
     - 'bin/**/*'
-    - 'lib/capistrano/ops/local/**/*'
 
 # Metrics
 

data/CHANGELOG.md

@@ -7,6 +7,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.2.0] - 2026-09-18
+
+### Added
+
+- Add `local:run` and `local:console` tasks (module `capistrano/ops/local`) to upload a local Ruby script from `scripts/local/` to the server and execute it — once via `rails runner`, or interactively with a Rails console
+- Helpers module `Capistrano::Ops::Local::Helpers` with script resolution (auto `.rb`), listing, TTY-aware coloring, and dangerous-stage confirmation
+- Configurable settings: `:local_scripts_dir`, `:local_dangerous_stages`; existing `:console_role`, `:console_env`, `:console_user`, `:console_shell` respected
+- Specs for helpers (script resolution, TTY coloring, tmp-path generation)
+- README section documenting the new tasks, including `capistrano-rails` prerequisite for `local:console`
+
 ## [1.1.0] - 2026-09-18
 
 ### Added
@@ -311,7 +321,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Figaro YAML management
 - Basic Capistrano integration
 
-[Unreleased]: https://github.com/zauberware/capistrano-ops/compare/v1.1.0...HEAD
+[Unreleased]: https://github.com/zauberware/capistrano-ops/compare/v1.2.0...HEAD
+[1.2.0]: https://github.com/zauberware/capistrano-ops/releases/tag/v1.2.0
 [1.1.0]: https://github.com/zauberware/capistrano-ops/releases/tag/v1.1.0
 [1.0.11]: https://github.com/zauberware/capistrano-ops/releases/tag/v1.0.11
 [v1.0.10]: https://github.com/zauberware/capistrano-ops/compare/v1.0.9...v1.0.10

data/README.md

@@ -24,6 +24,7 @@ The capistrano-ops gem is a valuable library, tailor-made for Rails DevOps profe
   - [Configuration](#configuration-1)
   - [Usage](#usage-1)
 - [Wkhtmltopdf Setup](#wkhtmltopdf-setup)
+- [Local scripts (run / console)](#local-scripts-run--console)
 - [Contributing](#contributing)
 - [License](#license)
 
@@ -170,6 +171,8 @@ require 'capistrano/ops'
 | `cap <environment> logrotate:enable`             | enable logrotate for logfiles on server                                  |
 | `cap <environment> logrotate:disable`            | disable logrotate for logfiles on server                                 |
 | `cap <environment> logrotate:check`              | show logrotate status for logfiles on server                             |
+| `cap <environment> local:run SCRIPT=<file>`      | upload local script and execute it once via `rails runner` on the server |
+| `cap <environment> local:console SCRIPT=<file>`  | open a remote Rails console with a local script preloaded                |
 | `rake pg:dump`                                   | creates postgres database backup                                         |
 | `rake pg:remove_old_dumps`                       | remove old postgres backups                                              |
 | `rake storage:backup`                            | creates backup of storage                                                |
@@ -390,6 +393,90 @@ require 'capistrano/ops/wkhtmltopdf'
 
 [↑](#)
 
+## Local scripts (run / console)
+
+Ship a Ruby script from your workstation onto the server and execute it there —
+either once via `rails runner`, or with a Rails console attached and the
+script's methods preloaded. Useful for one-off data patches, ad-hoc audits, or
+debugging sessions where you want your local scratch code to have full access
+to the production Rails environment.
+
+### Requirements
+
+`local:console` uses the interactive console runner shipped in `capistrano-rails`.
+Make sure both are loaded in your `Capfile`:
+
+```ruby
+# Capfile
+require 'capistrano/rails/console'   # provides run_interactively (needed by local:console)
+require 'capistrano/ops'             # auto-loads capistrano/ops/local
+```
+
+If `capistrano-rails` is not in your Gemfile, the `local:*` tasks will emit a
+warning at load time and skip registering. `local:run` alone technically only
+needs core Capistrano, but for simplicity both tasks share the same gate.
+
+### Setup
+
+Create the scripts directory in your app root (default `scripts/local/`) and
+drop `.rb` files in it:
+
+```
+scripts/local/
+├── check_stuck_jobs.rb
+└── set_welcome_email_template.rb
+```
+
+The directory is configurable:
+
+```ruby
+# config/deploy.rb
+set :local_scripts_dir, 'ops/scripts'   # default: 'scripts/local'
+```
+
+### Tasks
+
+```bash
+cap staging local:run     SCRIPT=check_stuck_jobs      # execute once via rails runner
+cap staging local:console SCRIPT=check_stuck_jobs      # open remote console with script preloaded
+```
+
+- `.rb` extension is optional (`SCRIPT=foo` and `SCRIPT=foo.rb` both work)
+- Omitting `SCRIPT=` prints the list of available scripts
+- Interactive `[y/N]` confirmation on "dangerous" stages (default: `production`)
+- Uploaded temp files are cleaned up automatically after execution
+
+### Writing scripts
+
+Define methods rather than top-level code — this way the same script works for
+both `local:run` (direct execution) and `local:console` (interactive access):
+
+```ruby
+# scripts/local/check_stuck_jobs.rb
+def show_stuck_jobs(hours_ago: 24)
+  cutoff = hours_ago.hours.ago
+  Sidekiq::Workers.new.select { |_, _, w| Time.at(w['run_at']) < cutoff }.each do |process, _, work|
+    puts "#{work['payload']['class']} on #{process}"
+  end
+end
+
+# auto-run when executed via local:run, dormant in the console
+show_stuck_jobs unless defined?(IRB)
+```
+
+### Configuration options
+
+| Setting                    | Default                         | Purpose                                        |
+| -------------------------- | ------------------------------- | ---------------------------------------------- |
+| `:local_scripts_dir`       | `'scripts/local'`               | Where local scripts are read from              |
+| `:local_dangerous_stages`  | `%w[production]`                | Stages that trigger the `[y/N]` confirmation   |
+| `:console_role`            | `:app`                          | Capistrano role used to pick the target host   |
+| `:console_env`             | `fetch(:rails_env) \|\| :stage` | Rails env passed to `rails runner` / `console` |
+| `:console_user`            | (unset)                         | `sudo -u` target user for the remote command   |
+| `:console_shell`           | (unset)                         | Shell override for the interactive session     |
+
+[↑](#)
+
 ## Contributing
 
 1. Fork it ( https://github.com/zauberware/capistrano-ops/fork )

data/lib/capistrano/ops/capistrano.rb

@@ -7,6 +7,7 @@ require 'capistrano/ops/logrotate'
 require 'capistrano/ops/logs'
 require 'capistrano/ops/invoke'
 require 'capistrano/ops/backup'
+require 'capistrano/ops/local'
 
 unless defined?(Capistrano::VERSION) && Gem::Version.new(Capistrano::VERSION).release >= Gem::Version.new('3.0.0')
   puts 'Capistrano 3 is required to use this gem'

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/version.rb

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

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: capistrano-ops
 version: !ruby/object:Gem::Version
-  version: 1.1.0
+  version: 1.2.0
 platform: ruby
 authors:
 - Florian Crusius
@@ -234,6 +234,10 @@ files:
 - lib/capistrano/ops/helper.rb
 - lib/capistrano/ops/invoke.rb
 - lib/capistrano/ops/invoke/tasks/invoke.rake
+- lib/capistrano/ops/local.rb
+- lib/capistrano/ops/local/helpers.rb
+- lib/capistrano/ops/local/tasks/console.rake
+- lib/capistrano/ops/local/tasks/run.rake
 - lib/capistrano/ops/logrotate.rb
 - lib/capistrano/ops/logrotate/helpers.rb
 - lib/capistrano/ops/logrotate/paths.rb
@@ -272,6 +276,7 @@ files:
 - lib/capistrano/ops/wkhtmltopdf/helpers.rb
 - lib/capistrano/ops/wkhtmltopdf/tasks/setup.rake
 - scripts/bump_version.rb
+- spec/capistrano/ops/local/helpers_spec.rb
 - spec/capistrano/ops/version_spec.rb
 - spec/spec_helper.rb
 homepage: https://github.com/zauberware/capistrano-ops