tomo 1.1.1 → 1.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '083da9eb981a0e551ee6411af3548a6faa92251c5365d2d0b13fbd316775d098'
-  data.tar.gz: 519e8bb883a768681162b460657925b398f1da3e86fde40470b808d1cd3dffe2
+  metadata.gz: 4e70a81efc32a7a80b37b26edc668de8daa510e7954884a3711d71ced6ef1bf8
+  data.tar.gz: eef6788e4b36c1cdad66170b6b616af8a08f890bc089a6c70e6a12132a061911
 SHA512:
-  metadata.gz: 74081358dbca4a6e9e5fbaefd4051c46a82d078433c36d1a31061699a1559930a8700e8206984742d1f91968f8c226d78e6012bbbccce29198b1faec8c9f3364
-  data.tar.gz: c06ad89b83b04d71314b6ea78afd460bbf3ad0ea3b24cb21312dcf6c6d78b41ff7cbb4886d147837a09e1149f2a4684c03225b30dfa834c828ddec160315e4d8
+  metadata.gz: 4425384a896b364775994859d7ea4307cac1abcbd507514d6f7289d6a684f6263cd7b17d250d280f6f2ccd596ed47f5d8f0871337dd5b69895aa74a0ea9c718e
+  data.tar.gz: 57a0929d3e1be161c7830449226327ee1c4f0e20f4949658ec02287c436c4fbb12e8a7f819a4525266beb29a8abd6381285aae27e21b6e753ac27028783dca1f

data/README.md

@@ -2,25 +2,25 @@
 
 [![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)
-[![Circle](https://circleci.com/gh/mattbrictson/tomo.svg?style=shield)](https://app.circleci.com/pipelines/github/mattbrictson/tomo?branch=master)
+[![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)
 
@@ -64,7 +62,7 @@ host "user@hostname.or.ip.address"
 set application: "my-rails-app"
 set deploy_to: "/var/www/%{application}"
 set git_url: "git@github.com:my-username/my-rails-app.git"
-set git_branch: "master"
+set git_branch: "main"
 # ...
 
 setup do
@@ -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
 
@@ -225,7 +243,7 @@ Next run `tomo setup` for _both_ apps; this will set everything up for both user
 
 ## Support
 
-This project is a labor of love and I can only spend a few hours a week maintaining it, at most. If you'd like to help by submitting a pull request, or if you've discovered a bug that needs my attention, please let me know. Check out [CONTRIBUTING.md](https://github.com/mattbrictson/tomo/blob/master/CONTRIBUTING.md) to get started. Happy hacking! —Matt
+This project is a labor of love and I can only spend a few hours a week maintaining it, at most. If you'd like to help by submitting a pull request, or if you've discovered a bug that needs my attention, please let me know. Check out [CONTRIBUTING.md](https://github.com/mattbrictson/tomo/blob/main/CONTRIBUTING.md) to get started. Happy hacking! —Matt
 
 ## License
 
@@ -233,8 +251,8 @@ The gem is available as open source under the terms of the [MIT License](https:/
 
 ## Code of conduct
 
-Everyone interacting in the Tomo project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/mattbrictson/tomo/blob/master/CODE_OF_CONDUCT.md).
+Everyone interacting in the Tomo project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/mattbrictson/tomo/blob/main/CODE_OF_CONDUCT.md).
 
 ## Contribution guide
 
-Interested in filing a bug report, feature request, or opening a PR? Excellent! Please read the short [CONTRIBUTING.md](https://github.com/mattbrictson/tomo/blob/master/CONTRIBUTING.md) guidelines before you dive in.
+Interested in filing a bug report, feature request, or opening a PR? Excellent! Please read the short [CONTRIBUTING.md](https://github.com/mattbrictson/tomo/blob/main/CONTRIBUTING.md) guidelines before you dive in.

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
@@ -55,7 +55,6 @@ module Tomo
       argv << "" if argv.shift == "--complete"
     end
 
-    # rubocop:disable Metrics/CyclomaticComplexity
     def lookup_command(argv)
       command_name = argv.first unless Completions.active? && argv.length == 1
       command_name = Abbrev.abbrev(COMMANDS.keys)[command_name]
@@ -65,7 +64,6 @@ module Tomo
       command = COMMANDS[command_name] || Tomo::Commands::Default
       [command, command_name]
     end
-    # rubocop:enable Metrics/CyclomaticComplexity
 
     def task_format?(arg)
       arg.to_s.match?(/\A\S+:\S*\z/)

data/lib/tomo/cli/common_options.rb

@@ -1,22 +1,15 @@
 module Tomo
   class CLI
     module CommonOptions
-      # rubocop:disable Metrics/MethodLength
-      def self.included(mod)
+      def self.included(mod) # rubocop:disable Metrics/MethodLength
         mod.class_eval do
-          option :color,
-                 "--[no-]color",
-                 "Enable/disable color output" do |color|
+          option :color, "--[no-]color", "Enable/disable color output" do |color|
             Colors.enabled = color
           end
-          option :debug,
-                 "--[no-]debug",
-                 "Enable/disable verbose debug logging" do |debug|
+          option :debug, "--[no-]debug", "Enable/disable verbose debug logging" do |debug|
             Tomo.debug = debug
           end
-          option :trace,
-                 "--[no-]trace",
-                 "Display full backtrace on error" do |trace|
+          option :trace, "--[no-]trace", "Display full backtrace on error" do |trace|
             CLI.show_backtrace = trace
           end
           option :help, "-h, --help", "Print this documentation" do |_help|
@@ -27,7 +20,6 @@ module Tomo
           after_parse :dump_runtime_info
         end
       end
-      # rubocop:enable Metrics/MethodLength
 
       private
 

data/lib/tomo/cli/deploy_options.rb

@@ -1,8 +1,7 @@
 module Tomo
   class CLI
     module DeployOptions
-      # rubocop:disable Metrics/MethodLength
-      def self.included(mod)
+      def self.included(mod) # rubocop:disable Metrics/MethodLength
         mod.class_eval do
           option :environment,
                  "-e, --environment ENVIRONMENT",
@@ -23,7 +22,6 @@ module Tomo
           after_parse :prompt_for_environment
         end
       end
-      # rubocop:enable Metrics/MethodLength
 
       private
 
@@ -49,10 +47,7 @@ module Tomo
         return if envs.empty?
         return unless Console.interactive?
 
-        options[:environment] = Console.menu(
-          "Choose an environment:",
-          choices: envs
-        )
+        options[:environment] = Console.menu("Choose an environment:", choices: envs)
       end
     end
   end

data/lib/tomo/cli/parser.rb

@@ -46,12 +46,7 @@ module Tomo
       attr_reader :rules, :usage, :after_parse_methods
 
       def evaluate(argv, state, literal:)
-        RulesEvaluator.evaluate(
-          rules: rules.to_a,
-          argv: argv,
-          state: state,
-          literal: literal
-        )
+        RulesEvaluator.evaluate(rules: rules.to_a, argv: argv, state: state, literal: literal)
       end
 
       def check_required_rules(state)

data/lib/tomo/cli/project_options.rb

@@ -3,9 +3,7 @@ module Tomo
     module ProjectOptions
       def self.included(mod)
         mod.class_eval do
-          option :project,
-                 "-c, --config PATH",
-                 "Location of project config (default: #{DEFAULT_CONFIG_PATH})"
+          option :project, "-c, --config PATH", "Location of project config (default: #{DEFAULT_CONFIG_PATH})"
         end
       end
 

data/lib/tomo/cli/rules.rb

@@ -51,21 +51,11 @@ module Tomo
       attr_reader :rules
 
       def optional_arg_rule(spec, values_proc)
-        Rules::Argument.new(
-          spec,
-          values_proc: values_proc,
-          required: false,
-          multiple: false
-        )
+        Rules::Argument.new(spec, values_proc: values_proc, required: false, multiple: false)
       end
 
       def required_arg_rule(spec, values_proc)
-        Rules::Argument.new(
-          spec,
-          values_proc: values_proc,
-          required: true,
-          multiple: false
-        )
+        Rules::Argument.new(spec, values_proc: values_proc, required: true, multiple: false)
       end
 
       def mutiple_optional_args_rule(spec, values_proc)
@@ -73,10 +63,7 @@ module Tomo
       end
 
       def on_off_switch_rule(key, name, _values_proc, callback_proc)
-        Rules::Switch.new(key,
-                          "--#{name}",
-                          "--no-#{name}",
-                          callback_proc: callback_proc) do |arg|
+        Rules::Switch.new(key, "--#{name}", "--no-#{name}", callback_proc: callback_proc) do |arg|
           arg == "--#{name}"
         end
       end
@@ -86,12 +73,7 @@ module Tomo
       end
 
       def value_switch_rule(key, *switches, values_proc, callback_proc)
-        Rules::ValueSwitch.new(
-          key,
-          *switches,
-          values_proc: values_proc,
-          callback_proc: callback_proc
-        )
+        Rules::ValueSwitch.new(key, *switches, values_proc: values_proc, callback_proc: callback_proc)
       end
     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,10 +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)
@@ -51,8 +51,7 @@ class Tomo::CLI::Rules
     end
 
     def raise_missing_value(switch)
-      raise Tomo::CLI::Error,
-            "Please specify a value for the #{yellow(switch)} option."
+      raise Tomo::CLI::Error, "Please specify a value for the #{yellow(switch)} option."
     end
   end
 end

data/lib/tomo/cli/rules_evaluator.rb

@@ -41,11 +41,7 @@ module Tomo
       def complete_if_needed(matched_rules, *matched_args)
         return unless Completions.active?
 
-        completions.print_completions_and_exit(
-          matched_rules,
-          *matched_args,
-          state: state
-        )
+        completions.print_completions_and_exit(matched_rules, *matched_args, state: state)
       end
 
       def remaining_rules
@@ -56,15 +52,9 @@ module Tomo
 
       def raise_unrecognized_args
         problem_arg = argv.first
-        type = if literal || !problem_arg.start_with?("-")
-                 "arg"
-               else
-                 "option"
-               end
+        type = literal || !problem_arg.start_with?("-") ? "arg" : "option"
 
-        raise CLI::Error,
-              "#{Colors.yellow(problem_arg)} is not a recognized #{type} "\
-              "for this tomo command."
+        raise CLI::Error, "#{Colors.yellow(problem_arg)} is not a recognized #{type} for this tomo command."
       end
     end
   end

data/lib/tomo/cli/usage.rb

@@ -18,9 +18,7 @@ module Tomo
       end
 
       def to_s
-        indent([
-          "", banner_proc.call, "Options:", "", indent(options_help), "\n"
-        ].join("\n"))
+        indent(["", banner_proc.call, "Options:", "", indent(options_help), "\n"].join("\n"))
       end
 
       private