tomo 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: a195d5ca53b88b0bb0b79a013fdf0526f4bbbca8d9e700960e4e055e9e82b520
+  data.tar.gz: 01f8f89d2bf321858481ec4581bce9c786ca461ebc4ddf730b9e984b94d904e1
+SHA512:
+  metadata.gz: 7f59074b4183c57008dd6c15d05dc7c1acdb5b07c4836ab21ef4da4df10d7718af2e6e758873920a226b95dcba432a14bbb1c24a0938967a061a54de28ef20c2
+  data.tar.gz: 15c1f50a0d2843c055421bc3f345c0a08530c15aaf85bd3bff48ac059d299ee9eff346ce7ced1c594cc30f27b6750a587124e5f69805d9bedecd67f8adfd8971

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2019 Matt Brictson
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,221 @@
+# 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)
+[![Circle](https://circleci.com/gh/mattbrictson/tomo.svg?style=shield)](https://circleci.com/gh/mattbrictson/tomo)
+[![Code Climate](https://codeclimate.com/github/mattbrictson/tomo/badges/gpa.svg)](https://codeclimate.com/github/mattbrictson/tomo)
+[![Say Thanks!](https://img.shields.io/badge/Say%20Thanks-!-1EAEDB.svg)](https://saythanks.io/to/mattbrictson)
+
+Tomo is a friendly command-line tool for deploying Rails apps. It is a new alternative to Capistrano, Mina, and Shipit that optimizes for simplicity and developer happiness.
+
+💻 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/>
+
+This project wouldn't be possible without the generosity of the open source Ruby community. Please support open source projects and your fellow developers by helping answer questions, contributing pull requests to improve code and documentation, or just [drop a note](https://saythanks.io/to/mattbrictson) to say thanks! ❤️
+
+---
+
+- [Quick start](#quick-start)
+- [Reference documentation](#reference-documentation)
+- [FAQ](#faq)
+- [Support](#support)
+- [License](#license)
+- [Code of conduct](#code-of-conduct)
+- [Contribution guide](#contribution-guide) [TODO]
+
+## Quick start
+
+Tomo is distributed as a ruby gem. To install:
+
+```
+$ gem install tomo
+```
+
+#### Getting help
+
+An easy way to kick the tires is to view the `--help`.
+
+![$ tomo --help](./readme_images/tomo-help.png)
+
+#### Configuring a project
+
+Let’s init a project to see how tomo is configured.
+
+![$ tomo init](./readme_images/tomo-init.png)
+
+The `.tomo/config.rb` file defines all the settings and tasks needed to setup and deploy a typical Rails project. An abbreviated version looks like this:
+
+```ruby
+# .tomo/config.rb
+
+plugin "git"
+plugin "bundler"
+plugin "rails"
+# ...
+
+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"
+# ...
+
+setup do
+  run "git:clone"
+  run "git:create_release"
+  run "bundler:install"
+  run "rails:db_schema_load"
+  # ...
+end
+
+deploy do
+  run "git:create_release"
+  run "core:symlink_shared"
+  run "core:write_release_json"
+  run "bundler:install"
+  run "rails:assets_precompile"
+  run "rails:db_migrate"
+  run "core:symlink_current"
+  # ...
+end
+```
+
+Eventually you'll want to edit the config file to specify the appropriate user and host, perhaps define some custom tasks, and tweak the settings to make them suitable for your Rails app. You can also take advantage of more advanced features like multiple hosts and environment-based config.
+
+#### Host setup
+
+With tomo, an initial deployment is separated into two distinct steps. The `setup` command prepares the host for its first deploy. Let’s take a look at the documentation with `--help`:
+
+![$ tomo setup --help](./readme_images/tomo-setup-help.png)
+
+We can simulate the setup operation with the `--dry-run` option. Let's try it:
+
+![$ tomo setup --dry-run](./readme_images/tomo-setup-dry-run.png)
+
+As you can see, the setup command in this project clones the git repository, installs ruby, node, bundler, and initializes the database. One the host is set up, it is ready for its first deploy.
+
+#### Performing a deploy
+
+Typically you only need to run `setup` once. From then on deploying a project is a matter of running the `deploy` command.
+
+![$ tomo deploy --help](./readme_images/tomo-deploy-help.png)
+
+Like `setup`, this can be simulated with `--dry-run`, like this:
+
+![$ tomo deploy --dry-run](./readme_images/tomo-deploy-dry-run.png)
+
+#### Running a single task
+
+Tomo can also `run` individual remote tasks. Use the `tasks` command to see the list of tasks tomo knows about.
+
+![$ tomo tasks](./readme_images/tomo-tasks.png)
+
+One of the built-in Rails tasks is `rails:console`, which brings up a fully-interactive Rails console over SSH. We can simulate this with `--dry-run` as well.
+
+![$ tomo run rails:console --dry-run](./readme_images/tomo-run-rails-console-dry-run.png)
+
+#### Writing tasks
+
+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:
+
+```ruby
+# .tomo/plugins/my-plugin.rb
+
+def hello
+  remote.run "echo", "hello", settings[:application]
+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
+# .tomo/config.rb
+
+plugin "./plugins/my-plugin.rb"
+```
+
+And run it!
+
+![$ tomo run my-plugin:hello --dry-run](./readme_images/tomo-run-hello-dry-run.png)
+
+#### Next steps
+
+And just like that, you are now already familiar with the basics of tomo and how to extend it! Tomo is even more friendly and powerful with the help of bash completions. If you use bash, run `tomo completion-script` for instructions on setting them up.
+
+To prepare your existing project for a real deploy, check out the sections of the reference documentation on [configuration](https://tomo-deploy.com/configuration/), [writing custom tasks](https://tomo-deploy.com/tutorials/writing-custom-tasks/) [TODO], the [setup command](https://tomo-deploy.com/commands/setup/), and the [deploy command](https://tomo-deploy.com/commands/deploy/). There is also a tutorial that walks through [deploying a new Rails app from scratch](https://tomo-deploy.com/tutorials/deploying-rails-from-scratch/) [TODO]. If you have questions, check out the [FAQ](#faq) and [support](#support) notes below. Enjoy using tomo!
+
+## Reference documentation
+
+- [Configuration](https://tomo-deploy.com/configuration/)
+- Commands
+  - [init](https://tomo-deploy.com/commands/init/)
+  - [setup](https://tomo-deploy.com/commands/setup/)
+  - [deploy](https://tomo-deploy.com/commands/deploy/)
+  - [run](https://tomo-deploy.com/commands/run/)
+  - [tasks](https://tomo-deploy.com/commands/tasks/)
+- Plugins
+  - [core](https://tomo-deploy.com/plugins/core/)
+  - [bundler](https://tomo-deploy.com/plugins/bundler/)
+  - [env](https://tomo-deploy.com/plugins/env/)
+  - [git](https://tomo-deploy.com/plugins/git/)
+  - [nvm](https://tomo-deploy.com/plugins/nvm/)
+  - [puma](https://tomo-deploy.com/plugins/puma/)
+  - [rails](https://tomo-deploy.com/plugins/rails/)
+  - [rbenv](https://tomo-deploy.com/plugins/rbenv/)
+- Tutorials
+  - [Deploying Rails From Scratch](https://tomo-deploy.com/tutorials/deploying-rails-from-scratch/) [TODO]
+  - [Writing Custom Tasks](https://tomo-deploy.com/tutorials/writing-custom-tasks/) [TODO]
+  - [Publishing a Plugin](https://tomo-deploy.com/tutorials/publishing-a-plugin/) [TODO]
+- API
+  - [Host](https://tomo-deploy.com/api/Host/)
+  - [Logger](https://tomo-deploy.com/api/Logger/)
+  - [Paths](https://tomo-deploy.com/api/Paths/)
+  - [PluginDSL](https://tomo-deploy.com/api/Host/)
+  - [Remote](https://tomo-deploy.com/api/Remote/)
+  - [Result](https://tomo-deploy.com/api/Result/)
+  - [TaskLibrary](https://tomo-deploy.com/api/TaskLibrary/)
+  - [Testing::MockPluginTester](https://tomo-deploy.com/api/testing/MockPluginTester/)
+  - [Testing::DockerPluginTester](https://tomo-deploy.com/api/testing/DockerPluginTester/)
+
+## FAQ
+
+#### What does the `unsupported option "accept-new"` error mean?
+
+By default, tomo uses the ["accept-new"](https://www.openssh.com/txt/release-7.6) value for the StrictHostKeyChecking option, which is supported by OpenSSH 7.6 and newer. If you are using an older version, this will cause an error. As a workaround, you can override tomo's default behavior like this:
+
+```ruby
+# Replace "accept-new" with something compatible with older versions of SSH
+set ssh_strict_host_key_checking: true # or false
+```
+
+## Support
+
+Thanks for your interest in Tomo! I use Tomo myself to deploy my own Rails projects and intend to keep this repository working and up to date for the foreseeable future. However Tomo is only a hobby, and as the sole maintainer, my ability to provide support and review pull request is limited and a bit sporadic. My priorities right now are:
+
+1. Improve test coverage
+2. Keep the project free of any serious bugs
+3. Stay up to date with the latest versions of Ruby and gem dependencies
+
+If you'd like to help by submitting a pull request, that would be much appreciated! Check out the contribution guide to get started.
+
+Otherwise if you want to report a bug, or have ideas, feedback or questions about Tomo, [let me know via GitHub issues](https://github.com/mattbrictson/tomo/issues/new) and I will do my best to provide a helpful answer. Happy hacking! —Matt
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+## 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).
+
+## Contribution guide
+
+[TODO]

data/exe/tomo

@@ -0,0 +1,4 @@
+#!/usr/bin/env ruby
+
+require "tomo"
+Tomo::CLI.new.call(ARGV)

data/lib/tomo/cli/command.rb

@@ -0,0 +1,36 @@
+require "forwardable"
+
+module Tomo
+  class CLI
+    class Command
+      class << self
+        extend Forwardable
+        def_delegators :parser, :arg, :option, :after_parse
+
+        def parser
+          @parser ||= Parser.new
+        end
+
+        def parse(argv)
+          command = new
+          parser.context = command
+          parser.banner = command.method(:banner)
+          *args, options = parser.parse(argv)
+          command.call(*args, options)
+        end
+      end
+
+      include Colors
+
+      private
+
+      def dry_run?
+        Tomo.dry_run?
+      end
+
+      def logger
+        Tomo.logger
+      end
+    end
+  end
+end

data/lib/tomo/cli/common_options.rb

@@ -0,0 +1,48 @@
+module Tomo
+  class CLI
+    module CommonOptions
+      # rubocop:disable Metrics/MethodLength
+      def self.included(mod)
+        mod.class_eval do
+          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|
+            Tomo.debug = debug
+          end
+          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|
+            puts instance_variable_get(:@parser)
+            exit
+          end
+
+          after_parse :dump_runtime_info
+        end
+      end
+      # rubocop:enable Metrics/MethodLength
+
+      private
+
+      def dump_runtime_info(*)
+        Tomo.logger.debug("tomo #{Tomo::VERSION}")
+        Tomo.logger.debug(RUBY_DESCRIPTION)
+        Tomo.logger.debug("rubygems #{Gem::VERSION}")
+        Tomo.logger.debug("bundler #{Bundler::VERSION}") if Tomo.bundled?
+
+        begin
+          require "concurrent"
+          Tomo.logger.debug("concurrent-ruby #{Concurrent::VERSION}")
+        rescue LoadError # rubocop:disable Lint/HandleExceptions
+        end
+      end
+    end
+  end
+end

data/lib/tomo/cli/completions.rb

@@ -0,0 +1,70 @@
+module Tomo
+  class CLI
+    class Completions
+      def self.activate
+        @active = true
+      end
+
+      def self.active?
+        !!@active
+      end
+
+      def initialize(literal: false, stdout: $stdout, exit_proc: nil)
+        @literal = literal
+        @stdout = stdout
+        @exit_proc = exit_proc || Kernel.method(:exit)
+      end
+
+      def print_completions_and_exit(rules, *args, state:)
+        completions = completions_for(rules, *args, state)
+        words = completions.map { |c| bash_word_for(c, args.last) }
+        stdout.puts(words.join("\n")) unless words.empty?
+        exit_proc.call
+      end
+
+      private
+
+      attr_reader :literal, :stdout, :exit_proc
+
+      def completions_for(rules, *prefix_args, word, state)
+        all_candidates(rules, prefix_args, state).select do |cand|
+          next if !literal && redundant_option_completion?(cand, word)
+
+          cand.start_with?(word) && cand != word
+        end
+      end
+
+      def all_candidates(rules, prefix_args, state)
+        rules.flat_map do |rule|
+          rule.candidates(*prefix_args, literal: literal, state: state)
+        end
+      end
+
+      def redundant_option_completion?(cand, word)
+        # Don't complete switches until the user has typed at least "--"
+        return true if cand.start_with?("-") && !word.start_with?("--")
+
+        # Don't complete the =value part of long switch unless the user has
+        # already typed at least up to the = sign.
+        return true if cand.match?(/\A--.*=/) && !word.match?(/\A--.*=/)
+      end
+
+      # bash tokenizes the user's input prior to completion, and expects the
+      # completions we return to be only the last token of the string. So if the
+      # user typed "rails:c[TAB]", bash expects the completion to be the part
+      # after the ":" character. In other words we should return "console", not
+      # "rails:console". The special tokens we need to consider are ":" and "=".
+      #
+      # For convenience we also distinguish a partial completion vs a full
+      # completion. If it is a full completion we append a " " to the end of
+      # the word so that the user can naturally begin typing the next option or
+      # argument.
+      def bash_word_for(completion, user_input)
+        completion = "#{completion} " unless completion.end_with?("=")
+        return completion unless user_input.match?(/[:=]/)
+
+        completion.sub(/.*[:=]/, "")
+      end
+    end
+  end
+end

data/lib/tomo/cli/deploy_options.rb

@@ -0,0 +1,59 @@
+module Tomo
+  class CLI
+    module DeployOptions
+      # rubocop:disable Metrics/MethodLength
+      def self.included(mod)
+        mod.class_eval do
+          option :environment,
+                 "-e, --environment ENVIRONMENT",
+                 "Specify environment to use (e.g. production)",
+                 values: :environment_names
+
+          option :settings,
+                 "-s, --setting NAME=VALUE",
+                 "Override setting NAME with the given VALUE",
+                 values: :setting_completions
+
+          option :dry_run,
+                 "--[no-]dry-run",
+                 "Simulate running tasks instead of using real SSH" do |dry|
+            Tomo.dry_run = dry
+          end
+
+          after_parse :prompt_for_environment
+        end
+      end
+      # rubocop:enable Metrics/MethodLength
+
+      private
+
+      def environment_names(*_args, options)
+        load_configuration(options).environments.keys
+      end
+
+      def setting_completions(*_args, options)
+        runtime = configure_runtime(options, strict: false)
+        settings = runtime.execution_plan_for([]).settings
+
+        settings = settings.select do |_key, value|
+          value.nil? || value.is_a?(String) || value.is_a?(Numeric)
+        end.to_h
+
+        settings.keys.map { |sett| "#{sett}=" }
+      end
+
+      def prompt_for_environment(*args, options)
+        return unless options[:environment].nil?
+
+        envs = environment_names(*args, options)
+        return if envs.empty?
+        return unless Console.interactive?
+
+        options[:environment] = Console.menu(
+          "Choose an environment:",
+          choices: envs
+        )
+      end
+    end
+  end
+end

data/lib/tomo/cli/error.rb

@@ -0,0 +1,16 @@
+module Tomo
+  class CLI
+    class Error < ::Tomo::Error
+      attr_accessor :command_name
+
+      def to_console
+        tomo_command = ["tomo", command_name].compact.join(" ")
+        <<~ERROR
+          #{message}
+
+          Run #{blue("#{tomo_command} -h")} for help.
+        ERROR
+      end
+    end
+  end
+end

data/lib/tomo/cli/interrupted_error.rb

@@ -0,0 +1,9 @@
+module Tomo
+  class CLI
+    class InterruptedError < Error
+      def to_console
+        "Interrupted"
+      end
+    end
+  end
+end

data/lib/tomo/cli/options.rb

@@ -0,0 +1,38 @@
+module Tomo
+  class CLI
+    class Options
+      def initialize
+        @options = {}
+      end
+
+      def any?
+        options.any?
+      end
+
+      def key?(key)
+        !all(key).empty?
+      end
+
+      def fetch(key, default)
+        values = all(key)
+        values.empty? ? default : values.first
+      end
+
+      def [](key)
+        fetch(key, nil)
+      end
+
+      def []=(key, value)
+        all(key).clear.push(value)
+      end
+
+      def all(key)
+        options[key] ||= []
+      end
+
+      private
+
+      attr_reader :options
+    end
+  end
+end

data/lib/tomo/cli/parser.rb

@@ -0,0 +1,92 @@
+require "forwardable"
+
+module Tomo
+  class CLI
+    class Parser
+      extend Forwardable
+      include Colors
+
+      def_delegators :usage, :banner=, :to_s
+
+      attr_accessor :context
+
+      def initialize
+        @rules = Rules.new
+        @usage = Usage.new
+        @after_parse_methods = []
+      end
+
+      def arg(spec, values: [])
+        rules.add_arg(spec, proc_for(values))
+      end
+
+      def option(key, spec, desc=nil, values: [], &block)
+        rules.add_option(key, spec, proc_for(values), &block)
+        usage.add_option(spec, desc)
+      end
+
+      def after_parse(context_method_name)
+        after_parse_methods << context_method_name
+      end
+
+      def parse(argv)
+        state = State.new
+
+        options_argv, literal_argv = split(argv, "--")
+        evaluate(options_argv, state, literal: false)
+        evaluate(literal_argv, state, literal: true)
+        check_required_rules(state)
+        invoke_after_parse_methods(state)
+
+        [*state.args, state.options]
+      end
+
+      private
+
+      attr_reader :rules, :usage, :after_parse_methods
+
+      def evaluate(argv, state, literal:)
+        RulesEvaluator.evaluate(
+          rules: rules.to_a,
+          argv: argv,
+          state: state,
+          literal: literal
+        )
+      end
+
+      def check_required_rules(state)
+        (rules.to_a - state.processed_rules).each do |rule|
+          next unless rule.required?
+
+          type = rule.is_a?(Rules::Argument) ? "" : " option"
+          raise CLI::Error, "Please specify the #{yellow(rule.to_s)}#{type}."
+        end
+      end
+
+      def invoke_after_parse_methods(state)
+        after_parse_methods.each do |method|
+          context.send(method, *state.args, state.options)
+        end
+      end
+
+      def proc_for(values)
+        return values if values.respond_to?(:call)
+        return proc { values } unless values.is_a?(Symbol)
+
+        method = values
+        proc { |*args| context.send(method, *args) }
+      end
+
+      def split(argv, delimiter)
+        index = argv.index(delimiter)
+        return [argv, []] if index.nil?
+        return [argv, []] if index == argv.length - 1 && Completions.active?
+
+        before = argv[0...index]
+        after = argv[(index + 1)..-1]
+
+        [before, after]
+      end
+    end
+  end
+end

data/lib/tomo/cli/project_options.rb

@@ -0,0 +1,47 @@
+module Tomo
+  class CLI
+    module ProjectOptions
+      def self.included(mod)
+        mod.class_eval do
+          option :project,
+                 "-c, --config PATH",
+                 "Location of project config (default: #{DEFAULT_CONFIG_PATH})"
+        end
+      end
+
+      private
+
+      def configure_runtime(options, strict: true)
+        config = load_configuration(options)
+        env = options[:environment]
+        env = config.environments.keys.first if env.nil? && !strict
+        config = config.for_environment(env)
+        config.settings.merge!(settings_from_env)
+        config.settings.merge!(settings_from_options(options))
+        config.build_runtime
+      end
+
+      def load_configuration(options)
+        path = options[:project] || DEFAULT_CONFIG_PATH
+        @config_cache ||= {}
+        @config_cache[path] ||= Configuration.from_config_rb(path)
+      end
+
+      def settings_from_options(options)
+        options.all(:settings).each_with_object({}) do |arg, settings|
+          name, value = arg.split("=", 2)
+          settings[name.to_sym] = value
+        end
+      end
+
+      def settings_from_env
+        ENV.each_with_object({}) do |(key, value), result|
+          setting_name = key[/^TOMO_(\w+)$/i, 1]&.downcase
+          next if setting_name.nil?
+
+          result[setting_name.to_sym] = value
+        end
+      end
+    end
+  end
+end