tomo 1.3.0 → 1.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '098582c6866a637c63527b1bf1fecd347686cf1472ddf4e93b11002180b4e0c3'
-  data.tar.gz: 74ea3479cd90f9d3cf038d7b8e6cffa0200a98a51562798ba1b852ca66866f4e
+  metadata.gz: c6e4c4920127adec0015456e7b666ecf2f58f7459c347d62b04ad337cdf8818c
+  data.tar.gz: e153c6374dcd288ce08125c70c973fb60f4f9d389020f19261d63dba97b1e925
 SHA512:
-  metadata.gz: 7ddd09600b3eae9914c7641b08f169f7f802297cf76170b7faffc0d0cb75cd0af22071c5e8d358c244464efe00672d4573054f30a2947b258aaef3af98e9ed74
-  data.tar.gz: 78c334db75ce535dd00c434fb3a4a927af4369d7f747cc3776334146c9c41bbae785ddb15e4ec42bdea59a66223a3836644f6bf0ec74e42f57c6de85fc822025
+  metadata.gz: eb670d2ab71b34098caee98bf44d47cc6a6a7c2e857541d33b9394588b4b294375ab91dbd1c071080fc5f70d893acf80acca09b1a863e99ad7c7994f6e7c6991
+  data.tar.gz: 14082e3582721a2816cfee25b8a613a8fc267e97e4b317b1cc87833f7150dd9ecee3af751ba123d4da06ea515d9d1913bda80cd9187311a9e9ab636a31b0b48e

data/README.md

@@ -1,26 +1,26 @@
 # Tomo
 
 [![Gem Version](https://badge.fury.io/rb/tomo.svg)](https://rubygems.org/gems/tomo)
-[![Travis](https://img.shields.io/travis/mattbrictson/tomo.svg?label=travis)](https://travis-ci.org/mattbrictson/tomo)
+[![Travis](https://img.shields.io/travis/com/mattbrictson/tomo.svg?label=travis)](https://travis-ci.com/github/mattbrictson/tomo)
 [![Circle](https://circleci.com/gh/mattbrictson/tomo/tree/main.svg?style=shield)](https://app.circleci.com/pipelines/github/mattbrictson/tomo?branch=main)
 [![Code Climate](https://codeclimate.com/github/mattbrictson/tomo/badges/gpa.svg)](https://codeclimate.com/github/mattbrictson/tomo)
 
-Tomo is a friendly command-line tool for deploying Rails apps. It is a new alternative to Capistrano, Mina, and Shipit that aims for simplicity and developer happiness.
+Tomo is a friendly command-line tool for deploying Rails apps.
 
 💻 Rich command-line interface with built-in bash completions<br/>
 ☁️ Multi-environment and role-based multi-host support<br/>
 💎 Everything you need to deploy a basic Rails app out of the box<br/>
 🔌 Easily extensible for polyglot projects (not just Rails!)<br/>
-💡 Concise, helpful error messages<br/>
 📚 Quality documentation<br/>
 🔬 Minimal dependencies<br/>
 
-See [how tomo compares](https://tomo-deploy.com/comparisons/) to other Ruby deployment tools.
+[→ See how tomo compares to other Ruby deployment tools like Capistrano and Mina.](https://tomo-deploy.com/comparisons/)
 
 ---
 
 - [Quick start](#quick-start)
 - [Usage](#usage)
+- [Extending tomo](#extending-tomo)
 - [Tutorials](#tutorials)
 - [Reference documentation](#reference-documentation)
 - [FAQ](#faq)
@@ -31,21 +31,19 @@ See [how tomo compares](https://tomo-deploy.com/comparisons/) to other Ruby depl
 
 ## Quick start
 
+#### Installation
+
 Tomo is distributed as a ruby gem. To install:
 
 ```
 $ gem install tomo
 ```
 
-For instructions on setting up bash completions, run:
-
-```
-$ tomo completion-script
-```
+> 💡 **Protip:** run `tomo completion-script` for instructions on setting up bash completions.
 
 #### Configuring a project
 
-Tomo is configured via a `.tomo/config.rb` file in your project. To get started, you can use `tomo init` to generate a configuration that works for a basic Rails app.
+Tomo is configured via a `.tomo/config.rb` file in your project. To get started, run `tomo init` to generate a configuration that works for a basic Rails app.
 
 ![$ tomo init](./readme_images/tomo-init.png)
 
@@ -87,20 +85,25 @@ deploy do
 end
 ```
 
-Check out the [configuration docs](https://tomo-deploy.com/configuration/) for a complete reference.
+#### Next steps
+
+[→ The reference docs have a complete guide to tomo configuration.](https://tomo-deploy.com/configuration/)<br>
+[→ Check out the **Deploying Rails From Scratch** tutorial for a step-by-step guide to using tomo with a real app.](https://tomo-deploy.com/tutorials/deploying-rails-from-scratch/)
 
 ## Usage
 
-Tomo gives you easy-to-use commands for three common use cases:
+Once your project is configured, you can:
+
+1. Run `tomo setup` to prepare the remote host for its first deploy.
+2. Run `tomo deploy` to deploy your app.
+3. Use `tomo run` to invoke one-off tasks, like launching a Rails console.
 
-1. `tomo setup` prepares a remote host for its first deploy
-2. `tomo deploy` performs a deployment
-3. `tomo run` lets you invoke one-off tasks
+> 💡 **Protip:** add `-h` or `--help` when running any of these commands to see detailed docs and examples.
 
-### Setup
+### `tomo setup`
 
 `tomo setup` prepares the remote host for its first deploy by sequentially running the
-[setup](https://tomo-deploy.com/configuration#setupblock) list of tasks specified in `.tomo/config.rb`. These tasks typically create directories, initialize data stores, install prerequisite tools, and perform other one-time actions that are necessary before a deploy can take place.
+`setup` list of tasks specified in `.tomo/config.rb`. These tasks typically create directories, initialize data stores, install prerequisite tools, and perform other one-time actions that are necessary before a deploy can take place.
 
 Out of the box, tomo will:
 
@@ -109,9 +112,12 @@ Out of the box, tomo will:
 - Create all necessary deployment directories
 - Create the Rails database, load the schema, and insert seed data
 
-### Deploy
+[→ Here is the default list of tasks invoked by the setup command.](https://tomo-deploy.com/configuration#setupblock)<br>
+[→ The `tomo setup` section of the reference docs explains supported command-line options.](https://tomo-deploy.com/commands/setup/)
 
-Whereas `tomo setup` is typically run once, you can use `tomo deploy` every time you want to deploy a new version of your app. The deploy command will sequentially run the [deploy](https://tomo-deploy.com/configuration#deployblock) list of tasks specified in `.tomo/config.rb`. You can customize this list to meet the needs of your app. By default, tomo runs these tasks:
+### `tomo deploy`
+
+Whereas `tomo setup` is typically run once, you can use `tomo deploy` every time you want to deploy a new version of your app. The deploy command will sequentially run the `deploy` list of tasks specified in `.tomo/config.rb`. You can customize this list to meet the needs of your app. By default, tomo runs these tasks:
 
 1. Create a release (using the [git:create_release](https://tomo-deploy.com/plugins/git#gitcreate_release) task)
 2. Build the project (e.g. [bundler:install](https://tomo-deploy.com/plugins/bundler#bundlerinstall), [rails:assets_precompile](https://tomo-deploy.com/plugins/rails#railsassets_precompile))
@@ -120,7 +126,13 @@ Whereas `tomo setup` is typically run once, you can use `tomo deploy` every time
 5. Restart the app to use the new current release (e.g. [puma:restart](https://tomo-deploy.com/plugins/puma#pumarestart))
 6. Perform any cleanup (e.g. [bundler:clean](https://tomo-deploy.com/plugins/bundler#bundlerclean))
 
-### Run
+> 💡 **Protip:** you can abbreviate tomo commands, like `tomo d` for `tomo deploy` or `tomo s` for `tomo setup`.
+
+[→ Here is the default list of tasks invoked by the deploy command.](https://tomo-deploy.com/configuration#deployblock)<br>
+[→ The `tomo deploy` section of the reference docs explains supported command-line options, like `--dry-run`.](https://tomo-deploy.com/commands/deploy/)
+
+
+### `tomo run [TASK]`
 
 Tomo can also `run` individual remote tasks on demand. You can use the `tasks` command to see the list of tasks tomo knows about.
 
@@ -130,9 +142,15 @@ One of the built-in Rails tasks is `rails:console`, which brings up a fully-inte
 
 ![$ tomo run rails:console](./readme_images/tomo-run-rails-console.png)
 
-### Extending tomo
+> 💡 **Protip:** you can shorten this as `tomo rails:console` (the `run` command is implied).
+
+[→ The `tomo run` section of the reference docs explains supported command-line options and has more examples.](https://tomo-deploy.com/commands/run/)
+
 
-Tomo has many plugins built-in, but you can easily add your own to extend tomo with custom tasks. By convention, custom plugins are stored in `.tomo/plugins/`. These plugins can define tasks as plain ruby methods. For example:
+
+## Extending tomo
+
+Tomo has a powerful plugin system that lets you extend tomo by installing Ruby gems (e.g. [tomo-plugin-sidekiq](https://github.com/mattbrictson/tomo-plugin-sidekiq)). You can also define plugins on the fly within your project by adding simple `.rb` files to `.tomo/plugins/`. These plugins can define tasks as plain ruby methods. For example:
 
 ```ruby
 # .tomo/plugins/my-plugin.rb
@@ -142,8 +160,6 @@ def hello
 end
 ```
 
-Use `remote.run` to execute shell scripts on the remote host, similar to how you would use Ruby's `system`. Project settings are accessible via `settings`, which is a plain Ruby hash.
-
 Load your plugin in `config.rb` like this:
 
 ```ruby
@@ -156,7 +172,9 @@ And run it!
 
 ![$ tomo run my-plugin:hello](./readme_images/tomo-run-hello.png)
 
-Read the [Writing Custom Tasks](https://tomo-deploy.com/tutorials/writing-custom-tasks/) tutorial for an in-depth guide to extending tomo.
+[→ The **Writing Custom Tasks** tutorial has an in-depth explanation of how plugins work.](https://tomo-deploy.com/tutorials/writing-custom-tasks/)<br>
+[→ The **TaskLibrary** API is tomo's DSL for building tasks.](https://tomo-deploy.com/api/TaskLibrary/)<br>
+[→ The **Publishing a Plugin** tutorial explains how to package your plugin as a Ruby gem to share it with the community.](https://tomo-deploy.com/tutorials/publishing-a-plugin/)
 
 ## Tutorials
 

data/lib/tomo/cli.rb

@@ -20,7 +20,7 @@ module Tomo
     class << self
       attr_accessor :show_backtrace
 
-      def exit(status=true)
+      def exit(status=true) # rubocop:disable Style/OptionalBooleanParameter
         Process.exit(status)
       end
     end

data/lib/tomo/cli/rules/argument.rb

@@ -1,6 +1,6 @@
 class Tomo::CLI::Rules
   class Argument
-    def initialize(label, multiple: false, required: false, values_proc:)
+    def initialize(label, values_proc:, multiple: false, required: false)
       @label = label
       @multiple = multiple
       @required = required
@@ -15,7 +15,7 @@ class Tomo::CLI::Rules
       state.parsed_arg(arg)
     end
 
-    def candidates(literal: false, state:)
+    def candidates(state:, literal: false)
       values(state).reject { |val| literal && val.start_with?("-") }
     end
 

data/lib/tomo/cli/rules/switch.rb

@@ -1,6 +1,6 @@
 class Tomo::CLI::Rules
   class Switch
-    def initialize(key, *switches, required: false, callback_proc:, &convert_proc)
+    def initialize(key, *switches, callback_proc:, required: false, &convert_proc)
       @key = key
       @switches = switches
       @callback_proc = callback_proc

data/lib/tomo/cli/rules/value_switch.rb

@@ -28,7 +28,7 @@ class Tomo::CLI::Rules
       state.parsed_option(key, value)
     end
 
-    def candidates(switch=nil, literal: false, state:)
+    def candidates(switch=nil, state:, literal: false)
       return [] if literal
 
       vals = values(state)

data/lib/tomo/commands/init.rb

@@ -1,4 +1,5 @@
 require "erb"
+require "fileutils"
 
 module Tomo
   module Commands
@@ -99,6 +100,10 @@ module Tomo
         Gem::Requirement.new(">= 2.2").satisfied_by?(erb_version)
       end
 
+      def ruby_version_file?
+        File.exist?(".ruby-version")
+      end
+
       def config_rb_template(app)
         path = File.expand_path("../templates/config.rb.erb", __dir__)
         template = IO.read(path)

data/lib/tomo/configuration.rb

@@ -90,7 +90,7 @@ module Tomo
       plugins_registry = PluginsRegistry.new
 
       (["core"] + plugins.uniq).each do |plug|
-        if %w[. /].include?(plug[0])
+        if plug.start_with?(".", "/")
           plug = File.expand_path(plug, File.dirname(path)) unless path.nil?
           plugins_registry.load_plugin_from_path(plug)
         else

data/lib/tomo/configuration/dsl/error_formatter.rb

@@ -50,7 +50,7 @@ module Tomo
           HINT
         end
 
-        def highlighted_lines
+        def highlighted_lines # rubocop:disable Metrics/AbcSize
           first = [1, error_line_no - 1].max
           last = [dsl_lines.length, error_line_no + 1].min
           width = last.to_s.length

data/lib/tomo/configuration/plugins_registry/gem_resolver.rb

@@ -55,7 +55,7 @@ module Tomo
 
       def scan_for_plugins
         Gem.find_latest_files("#{PLUGIN_PREFIX}/*.rb").map do |file|
-          file[%r{#{PLUGIN_PREFIX}/(.+).rb$}, 1].tr("/", "-")
+          file[%r{#{PLUGIN_PREFIX}/(.+).rb$}o, 1].tr("/", "-")
         end.uniq.sort
       end
     end

data/lib/tomo/paths.rb

@@ -20,7 +20,7 @@ module Tomo
       path(:"#{method}_path")
     end
 
-    def respond_to_missing?(method, include_private=false)
+    def respond_to_missing?(method, include_private)
       setting?(method) || super
     end
 

data/lib/tomo/plugin/bundler.rb

@@ -11,7 +11,7 @@ module Tomo::Plugin
     defaults bundler_config_path: ".bundle/config",
              bundler_deployment:  true,
              bundler_gemfile:     nil,
-             bundler_jobs:        "4",
+             bundler_jobs:        nil,
              bundler_path:        "%{shared_path}/bundle",
              bundler_retry:       "3",
              bundler_version:     nil,

data/lib/tomo/plugin/core.rb

@@ -21,7 +21,7 @@ module Tomo::Plugin
       releases_path:         "%{deploy_to}/releases",
       revision_log_path:     "%{deploy_to}/revisions.log",
       shared_path:           "%{deploy_to}/shared",
-      tmp_path:              "/tmp/tomo",
+      tmp_path:              "/tmp/tomo-#{SecureRandom.alphanumeric(8)}",
       tomo_config_file_path: nil, # determined at runtime
       run_args:              [] # determined at runtime
     )

data/lib/tomo/plugin/core/helpers.rb

@@ -12,7 +12,7 @@ module Tomo::Plugin::Core
       result.success?
     end
 
-    def write(text: nil, template: nil, to:, append: false, **run_opts)
+    def write(to:, text: nil, template: nil, append: false, **run_opts)
       assert_text_or_template_required!(text, template)
       text = merge_template(template) unless template.nil?
       message = "Writing #{text.bytesize} bytes to #{to}"

data/lib/tomo/plugin/core/tasks.rb

@@ -41,7 +41,7 @@ module Tomo::Plugin::Core
       current = read_current_release
 
       remote.chdir(paths.releases) do
-        releases = remote.list_files.grep(/^#{RELEASE_REGEXP}$/).sort
+        releases = remote.list_files.grep(/^#{RELEASE_REGEXP}$/o).sort
         desired_count -= 1 if releases.delete(current)
         return if releases.length <= desired_count
 
@@ -122,7 +122,7 @@ module Tomo::Plugin::Core
       result = remote.run("readlink", paths.current, raise_on_error: false, silent: true)
       return nil if result.failure?
 
-      result.stdout.strip[%r{/(#{RELEASE_REGEXP})$}, 1]
+      result.stdout.strip[%r{/(#{RELEASE_REGEXP})$}o, 1]
     end
   end
 end

data/lib/tomo/plugin/rbenv/tasks.rb

@@ -31,8 +31,7 @@ module Tomo::Plugin::Rbenv
     end
 
     def compile_ruby
-      require_setting :rbenv_ruby_version
-      ruby_version = settings[:rbenv_ruby_version]
+      ruby_version = version_setting || extract_ruby_ver_from_version_file
 
       unless ruby_installed?(ruby_version)
         logger.info(
@@ -51,5 +50,22 @@ module Tomo::Plugin::Rbenv
       end
       false
     end
+
+    def version_setting
+      settings[:rbenv_ruby_version]
+    end
+
+    def extract_ruby_ver_from_version_file
+      path = paths.release.join(".ruby-version")
+      version = remote.capture("cat", path, raise_on_error: false).strip
+      return version unless version.empty?
+
+      return RUBY_VERSION if dry_run?
+
+      die <<~REASON
+        Could not guess ruby version from .ruby-version file.
+        Use the :rbenv_ruby_version setting to specify the version of ruby to install.
+      REASON
+    end
   end
 end

data/lib/tomo/runtime/explanation.rb

@@ -7,7 +7,7 @@ module Tomo
         @concurrency = concurrency
       end
 
-      def to_s # rubocop:disable Metrics/MethodLength, Metrics/AbcSize, Metrics/CyclomaticComplexity
+      def to_s # rubocop:disable Metrics/MethodLength, Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
         desc = []
         threads = [applicable_hosts.length, concurrency].min
         desc << "CONCURRENTLY (#{threads} THREADS):" if threads > 1

data/lib/tomo/shell_builder.rb

@@ -82,7 +82,7 @@ module Tomo
     end
 
     def export_env
-      exports = @env.reject { |_, value| value.nil? }
+      exports = @env.compact
       return if exports.empty?
 
       [

data/lib/tomo/ssh/connection.rb

@@ -26,7 +26,7 @@ module Tomo
       end
 
       def ssh_subprocess(script, verbose: false)
-        ssh_args = build_args(script, verbose)
+        ssh_args = build_args(script, verbose: verbose)
         handle_data = ->(data) { logger.script_output(script, data) }
 
         logger.script_start(script)
@@ -50,7 +50,7 @@ module Tomo
         Tomo.logger
       end
 
-      def build_args(script, verbose=false)
+      def build_args(script, verbose: false)
         options.build_args(host, script, control_path, verbose)
       end
 

data/lib/tomo/ssh/connection_validator.rb

@@ -15,10 +15,10 @@ module Tomo
 
       def assert_valid_executable!
         result = begin
-                   ChildProcess.execute(executable, "-V")
-                 rescue StandardError => e
-                   handle_bad_executable(e)
-                 end
+          ChildProcess.execute(executable, "-V")
+        rescue StandardError => e
+          handle_bad_executable(e)
+        end
 
         Tomo.logger.debug(result.output)
         return if result.success? && supported?(result.output)

data/lib/tomo/templates/config.rb.erb

@@ -14,7 +14,9 @@ host "user@hostname.or.ip.address"
 
 set application: <%= app.inspect %>
 set deploy_to: "/var/www/%{application}"
+<% unless ruby_version_file? -%>
 set rbenv_ruby_version: <%= RUBY_VERSION.inspect %>
+<% end -%>
 set nodenv_node_version: <%= node_version&.inspect || "nil # FIXME" %>
 set nodenv_yarn_version: <%= yarn_version.inspect %>
 set git_url: <%= git_origin_url&.inspect || "nil # FIXME" %>

data/lib/tomo/testing/cli_extensions.rb

@@ -1,7 +1,7 @@
 module Tomo
   module Testing
     module CLIExtensions
-      def exit(status=true)
+      def exit(status=true) # rubocop:disable Style/OptionalBooleanParameter
         raise MockedExitError, status
       end
     end

data/lib/tomo/testing/docker_image.rb

@@ -80,9 +80,9 @@ module Tomo
       end
 
       def build_image
-        Local.capture(
-          "docker build #{build_dir}"
-        )[/Successfully built (\S+)$/i, 1]
+        tag = "tomo_testing:latest"
+        Local.capture("docker build --tag #{tag} #{build_dir}")
+        tag
       end
 
       def start_container

data/lib/tomo/version.rb

@@ -1,3 +1,3 @@
 module Tomo
-  VERSION = "1.3.0".freeze
+  VERSION = "1.6.0".freeze
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: tomo
 version: !ruby/object:Gem::Version
-  version: 1.3.0
+  version: 1.6.0
 platform: ruby
 authors:
 - Matt Brictson
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2020-08-08 00:00:00.000000000 Z
+date: 2021-01-01 00:00:00.000000000 Z
 dependencies: []
 description: Tomo is a feature-rich deployment tool that contains everything you need
   to deploy a basic Rails app out of the box. It has an opinionated, production-tested
@@ -65,7 +65,6 @@ files:
 - lib/tomo/configuration/environment.rb
 - lib/tomo/configuration/glob.rb
 - lib/tomo/configuration/plugin_file_not_found_error.rb
-- lib/tomo/configuration/plugin_resolver.rb
 - lib/tomo/configuration/plugins_registry.rb
 - lib/tomo/configuration/plugins_registry/file_resolver.rb
 - lib/tomo/configuration/plugins_registry/gem_resolver.rb
@@ -189,7 +188,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.1.4
+rubygems_version: 3.2.3
 signing_key:
 specification_version: 4
 summary: A friendly CLI for deploying Rails apps ✨

data/lib/tomo/configuration/plugin_resolver.rb

@@ -1,63 +0,0 @@
-module Tomo
-  class Configuration
-    class PluginResolver
-      PLUGIN_PREFIX = "tomo/plugin".freeze
-      private_constant :PLUGIN_PREFIX
-
-      def self.resolve(name)
-        new(name).plugin_module
-      end
-
-      def initialize(name)
-        @name = name
-      end
-
-      def plugin_module
-        plugin_path = [PLUGIN_PREFIX, name.tr("-", "/")].join("/")
-        require plugin_path
-
-        plugin = constantize(plugin_path)
-        assert_compatible_api(plugin)
-
-        plugin
-      rescue LoadError => e
-        raise unless e.message.match?(/\s#{Regexp.quote(plugin_path)}$/)
-
-        raise_unknown_plugin_error(e)
-      end
-
-      private
-
-      attr_reader :name
-
-      def assert_compatible_api(plugin)
-        return if plugin.is_a?(::Tomo::PluginDSL)
-
-        raise "#{plugin} does not extend Tomo::PluginDSL"
-      end
-
-      def constantize(path)
-        parts = path.split("/")
-        parts.reduce(Object) do |parent, part|
-          child = part.gsub(/^[a-z]|_[a-z]/) { |str| str[-1].upcase }
-          parent.const_get(child, false)
-        end
-      end
-
-      def raise_unknown_plugin_error(error)
-        UnknownPluginError.raise_with(
-          error.message,
-          name: name,
-          gem_name: "#{PLUGIN_PREFIX}/#{name}".tr("/", "-"),
-          known_plugins: scan_for_plugins
-        )
-      end
-
-      def scan_for_plugins
-        Gem.find_latest_files("#{PLUGIN_PREFIX}/*.rb").map do |file|
-          file[%r{#{PLUGIN_PREFIX}/(.+).rb$}, 1].tr("/", "-")
-        end.uniq.sort
-      end
-    end
-  end
-end