cli-kit 3.0.0 → 4.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: 88690eeba1179ef8cb31ebd13b68d978e71f5c8a
-  data.tar.gz: f63da3dc52f120f759241232fb64953deb0e0b3f
+SHA256:
+  metadata.gz: 523252459712e507c4579e244e6330eb3e8a5d8c71334d4e41553903ab651cd6
+  data.tar.gz: 459cb0a684e2890718d0cffdd74cd8540bd91a1995dfe1db593df9a189da20d7
 SHA512:
-  metadata.gz: abd4591db97ad44a9ebdf3645181ad90b443ad70d3849b3f247cf577cc394b04638646d14ab1cc18273d05a3a55cb1cdb3022ce9052792b025a7498c6d94a309
-  data.tar.gz: 6c8571d319162adfeb0dd66c294fb225565c10e50fdcb70ab60dcd4bbd705131ec43916691c8ce160939348491ec453d5b1054a2504bc13594e76aecc20cdf01
+  metadata.gz: 8579924711573ce6338b52dc44c47ad40c12f925bbd6f3ad6cee5be9f44b2b4f315e6d272adc309788b0418ee6806567660f0386d7e91d9d09a524beeb0a4a1f
+  data.tar.gz: b5507292ba97fd6f13b83b6426e81e4500e0ef1480387164c936164b7593bf7daac98e39cbb835362f198c39e562f2d12adf92384365a9c99a7f0ed42c158a45

data/.github/CODEOWNERS

@@ -0,0 +1 @@
+@Shopify/dev-infra

data/.github/dependabot.yml

@@ -0,0 +1,10 @@
+version: 2
+
+updates:
+- package-ecosystem: bundler
+  directory: "/"
+  schedule:
+    interval: weekly
+    time: "07:00"
+    timezone: America/Toronto
+  open-pull-requests-limit: 99

data/.github/probots.yml

@@ -0,0 +1,2 @@
+enabled:
+  - cla

data/.github/workflows/ruby.yml

@@ -0,0 +1,32 @@
+name: Ruby
+
+on: [push, pull_request]
+
+jobs:
+  style:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v2
+    - name: Set up Ruby
+      uses: ruby/setup-ruby@v1
+      with:
+        ruby-version: '2.7'
+        bundler-cache: true
+    - name: Check style
+      run: bundle exec rake style
+  test:
+    strategy:
+      matrix:
+        os: [macos-latest, ubuntu-latest, windows-latest]
+        ruby-version: ['2.6', '2.7']
+
+    runs-on: ${{ matrix.os }}
+    steps:
+    - uses: actions/checkout@v2
+    - name: Set up Ruby
+      uses: ruby/setup-ruby@v1
+      with:
+        ruby-version: ${{ matrix.ruby-version }}
+        bundler-cache: true
+    - name: Run tests
+      run: bundle exec rake test

data/.rubocop.yml

@@ -1,22 +1,21 @@
-inherit_from:
-  - http://shopify.github.io/ruby-style-guide/rubocop.yml
+inherit_gem:
+  rubocop-shopify: rubocop-cli.yml
 
 AllCops:
-  Exclude: [ 'gen/template/**/*' ]
-  TargetRubyVersion: 2.3
+  Exclude:
+    - gen/template/**/*
+    - vendor/**/*
+  TargetRubyVersion: 2.5
 
-Style/FrozenStringLiteralComment:
-  Enabled: false
-
-Shopify/RubocopComments:
-  Enabled: false
+Style/ClassAndModuleChildren:
+  Exclude:
+    - lib/cli/kit/support/test_helper.rb
 
-# This doesn't understand that <<~ doesn't exist in 2.0
-Layout/IndentHeredoc:
+Style/FrozenStringLiteralComment:
   Enabled: false
 
 # This doesn't take into account retrying from an exception
-Lint/HandleExceptions:
+Lint/SuppressedException:
   Enabled: false
 
 # allow String.new to create mutable strings
@@ -35,6 +34,5 @@ Style/RegexpLiteral:
 Style/MultilineBlockChain:
   Enabled: false
 
-# allow using names to be more expressive
-Performance/RedundantBlockCall:
-  Enabled: false
+Style/StringLiterals:
+  EnforcedStyle: single_quotes

data/Gemfile

@@ -1,16 +1,17 @@
 # NOTE: These are development-only dependencies
-source "https://rubygems.org"
+source 'https://rubygems.org'
 
 gemspec
 
 group :development, :test do
   gem 'rubocop'
+  gem 'rubocop-shopify'
   gem 'byebug'
   gem 'method_source'
 end
 
 group :test do
-  gem 'mocha', require: false
+  gem 'mocha', '~> 1.13.0', require: false
   gem 'minitest', '>= 5.0.0', require: false
   gem 'minitest-reporters', require: false
 end

data/Gemfile.lock

@@ -1,57 +1,62 @@
 PATH
   remote: .
   specs:
-    cli-kit (3.0.0)
-      cli-ui (>= 1.1.0)
+    cli-kit (4.0.0)
+      cli-ui (>= 1.1.4)
 
 GEM
   remote: https://rubygems.org/
   specs:
     ansi (1.5.0)
-    ast (2.3.0)
-    builder (3.2.3)
-    byebug (9.0.6)
-    cli-ui (1.1.0)
-    metaclass (0.0.4)
-    method_source (0.8.2)
-    minitest (5.10.2)
-    minitest-reporters (1.1.14)
+    ast (2.4.2)
+    builder (3.2.4)
+    byebug (11.1.3)
+    cli-ui (1.5.1)
+    method_source (1.0.0)
+    minitest (5.14.4)
+    minitest-reporters (1.4.3)
       ansi
       builder
       minitest (>= 5.0)
       ruby-progressbar
-    mocha (1.2.1)
-      metaclass (~> 0.0.1)
-    parallel (1.11.2)
-    parser (2.4.0.0)
-      ast (~> 2.2)
-    powerpack (0.1.1)
-    rainbow (2.2.2)
-      rake
-    rake (10.5.0)
-    rubocop (0.49.1)
+    mocha (1.13.0)
+    parallel (1.21.0)
+    parser (3.0.2.0)
+      ast (~> 2.4.1)
+    rainbow (3.0.0)
+    rake (13.0.6)
+    regexp_parser (2.1.1)
+    rexml (3.2.5)
+    rubocop (1.22.3)
       parallel (~> 1.10)
-      parser (>= 2.3.3.1, < 3.0)
-      powerpack (~> 0.1)
-      rainbow (>= 1.99.1, < 3.0)
+      parser (>= 3.0.0.0)
+      rainbow (>= 2.2.2, < 4.0)
+      regexp_parser (>= 1.8, < 3.0)
+      rexml
+      rubocop-ast (>= 1.12.0, < 2.0)
       ruby-progressbar (~> 1.7)
-      unicode-display_width (~> 1.0, >= 1.0.1)
-    ruby-progressbar (1.8.1)
-    unicode-display_width (1.3.0)
+      unicode-display_width (>= 1.4.0, < 3.0)
+    rubocop-ast (1.12.0)
+      parser (>= 3.0.1.1)
+    rubocop-shopify (2.3.0)
+      rubocop (~> 1.22)
+    ruby-progressbar (1.11.0)
+    unicode-display_width (2.1.0)
 
 PLATFORMS
   ruby
 
 DEPENDENCIES
-  bundler (~> 1.15)
+  bundler (~> 2.1)
   byebug
   cli-kit!
   method_source
   minitest (>= 5.0.0)
   minitest-reporters
-  mocha
-  rake (~> 10.0)
+  mocha (~> 1.13.0)
+  rake (~> 13.0)
   rubocop
+  rubocop-shopify
 
 BUNDLED WITH
-   1.16.0
+   2.2.24

data/README.md

@@ -11,8 +11,106 @@
 to build a number of internal developer tools, along with
 [cli-ui](https://github.com/shopify/cli-ui).
 
-## Example Usage
+## Getting Started
 
-You can see example usage [here](https://github.com/Shopify/cli-kit-example). We may one day build
-an application generator, as this framework paradigm requires a small amount of boilerplate. For
-now, the best way to get going is to use this example application as a starting point.
+To begin creating your first `cli-kit` application, run:
+```bash
+gem install cli-kit
+cli-kit new myproject
+```
+
+Where `myproject` is the name of the application you wish to create.  Then, you will be prompted to
+select how the project consumes `cli-kit` and `cli-ui`.  The available options are:
+- Vendor (faster execution, more difficult to update dependencies)
+- Bundler (slower execution, easier dependency management)
+
+You're now ready to write your very first `cli-kit` application!
+
+## How do `cli-kit` Applications Work?
+
+The executable for your `cli-kit` app is stored in the "exe" directory.  To execute the app, simply
+run:
+```bash
+./exe/myproject
+```
+
+### Folder Structure
+* `/exe/` - Location of the executables for your application.
+* `/lib/` - Location of the resources for your app (modules, classes, helpers, etc).
+    * `myproject.rb` - This file is the starting point for where to look for all other files. It
+    configures autoload and autocall for the app.
+    * `myproject/` - Stores the various commands/entry points.
+        * `entry_point.rb` - This is the file that is first called from the executable. It handles 
+        loading and commands.
+        * `commands.rb` - Registers the various commands that your application is able to handle.
+        * `commands/` - Stores Ruby files for each command (help, new, add, etc).
+
+## Adding a New Command to your App
+
+### Registering the Command
+
+Let's say that you'd like your program to be able to handle a specific task, and you'd like to
+_register_ a new handler for the command for that task, like `myproject add` to add 2 numbers, like
+in a calculator app.
+To do this, open `/lib/myproject/commands.rb`. Then, add a new line into the module, like this:
+```ruby
+register :Add, 'add', 'myproject/commands/add'
+```
+
+The format for this is `register :<CommandClass>, '<command-at-cli>', '<path/to/command.rb>'`
+
+### Creating the Command Action
+
+The action for a specific command is stored in its own Ruby file, in the `/lib/myproject/commands/`
+directory.  Here is an example of the `add` command in our previous to-do app example:
+```ruby
+require 'myproject'
+
+module Myproject
+  module Commands
+    class Add < Myproject::Command
+      def call(args, _name)
+        # command action goes here
+      end
+
+      def self.help
+        # help or instructions go here
+      end
+    end
+  end
+end
+
+```
+
+The `call(args, _name)` method is what actually runs when the `myproject add` command is executed.
+
+- **Note:** The `args` parameter represents all the arguments the user has specified.
+
+Let's say that you are trying to compute the sum of 2 numbers that the user has specified as
+arguments.  For example:
+```ruby
+def call(args, _name)
+  sum = args.map(&:to_i).inject(&:+)
+  puts sum
+end
+```
+
+### Getting Help
+
+Above, you'll notice that we also have a `self.help` method.  This method is what runs when the user
+has incorrectly used the command, or has requested help.  For example:
+```ruby
+def self.help
+  "Print the sum of 2 numbers.\nUsage: {{command:#{Myproject::TOOL_NAME} add}} 5 7"
+end
+```
+
+## User Interfaces
+
+`cli-kit` also features `cli-ui`, another gem from us here at Shopify, which allows for the use of
+powerful command-line user interface elements. For more details on how to use `cli-ui`, visit the 
+[`cli-ui`](https://github.com/Shopify/cli-ui) repo.
+
+## Examples
+
+- [A Simple To-Do App](https://github.com/Shopify/cli-kit-example)

data/Rakefile

@@ -0,0 +1,27 @@
+$LOAD_PATH.unshift(File.expand_path('../lib', __FILE__))
+require 'rake/testtask'
+require 'rubocop/rake_task'
+require 'bundler/gem_tasks'
+
+TEST_ROOT = File.expand_path('../test', __FILE__)
+
+Rake::TestTask.new do |t|
+  t.libs += ['test']
+  t.test_files = FileList[File.join(TEST_ROOT, '**', '*_test.rb')]
+  t.verbose = false
+  t.warning = false
+end
+
+RuboCop::RakeTask.new(:style) do |t|
+  t.options = ['--display-cop-names']
+end
+
+task :test_gen_bundler do
+  sh 'DEPS=bundler bin/test_gen'
+end
+
+task :test_gen_vendor do
+  sh 'DEPS=vendor bin/test_gen'
+end
+
+task(default: [:test, :style, :test_gen_bundler, :test_gen_vendor])

data/TODO.md

@@ -0,0 +1,5 @@
+* Build a help system
+* Build a tabular data formatter
+* Suppress colour by default when printing to non-TTY
+* Do frames in a way that works on BK when running on BK
+

data/bin/console

@@ -1,7 +1,7 @@
 #!/usr/bin/env ruby
 
-require "bundler/setup"
-require "cli/kit"
+require 'bundler/setup'
+require 'cli/kit'
 
 # You can add fixtures and/or initialization code here to make experimenting
 # with your gem easier. You can also use a different console, if you like.
@@ -10,5 +10,5 @@ require "cli/kit"
 # require "pry"
 # Pry.start
 
-require "irb"
+require 'irb'
 IRB.start(__FILE__)

data/bin/test_gen

@@ -0,0 +1,31 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Make sure we're in the cli kit directory
+CURR_DIR=$(dirname "$0")
+cd $CURR_DIR
+cd ../
+
+# Clean up
+function finish {
+  cd $CURR_DIR
+  cd ../../
+  rm -rf myapp
+}
+trap finish EXIT
+
+# Generate app and move up a level to be at the same level as cli-kit
+bundle exec ruby exe/cli-kit new myapp
+mv myapp ../
+cd ../myapp
+
+# Test
+if [[ $DEPS == 'bundler' ]]; then
+  bundle install
+fi
+bin/testunit
+
+if [[ $DEPS == 'vendor' ]]; then
+  git clone https://github.com/Shopify/cli-ui.git ../cli-ui
+  bin/update-deps
+fi

data/bin/testunit

@@ -9,12 +9,12 @@ CLI_TEST_ROOT = root + '/test'
 $LOAD_PATH.unshift(CLI_TEST_ROOT)
 
 def test_files
-  Dir.glob(CLI_TEST_ROOT + "/**/*_test.rb")
+  Dir.glob(CLI_TEST_ROOT + '/**/*_test.rb')
 end
 
 if ARGV.empty?
   test_files.each { |f| require(f) }
-  exit 0
+  exit(0)
 end
 
 # A list of files is presumed to be specified

data/cli-kit.gemspec

@@ -1,4 +1,5 @@
 # coding: utf-8
+
 lib = File.expand_path('../lib', __FILE__)
 $LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
 require 'cli/kit/version'
@@ -6,24 +7,24 @@ require 'cli/kit/version'
 Gem::Specification.new do |spec|
   spec.name          = 'cli-kit'
   spec.version       = CLI::Kit::VERSION
-  spec.authors       = ['Burke Libbey', 'Julian Nadeau', 'Lisa Ugray']
-  spec.email         = ['burke.libbey@shopify.com', 'julian.nadeau@shopify.com', 'lisa.ugray@shopify.com']
+  spec.authors       = ['Burke Libbey', 'Aaron Olson', 'Lisa Ugray']
+  spec.email         = ['burke.libbey@shopify.com', 'aaron.olson@shopify.com', 'lisa.ugray@shopify.com']
 
   spec.summary       = 'Terminal UI framework extensions'
   spec.description   = 'Terminal UI framework extensions'
   spec.homepage      = 'https://github.com/shopify/cli-kit'
   spec.license       = 'MIT'
 
-  spec.files = `git ls-files -z`.split("\x0").reject do |f|
+  spec.files = %x(git ls-files -z).split("\x0").reject do |f|
     f.match(%r{^(test|spec|features)/})
   end
   spec.bindir        = 'exe'
   spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
   spec.require_paths = ['lib']
 
-  spec.add_runtime_dependency 'cli-ui', '>= 1.1.0'
+  spec.add_runtime_dependency('cli-ui', '>= 1.1.4')
 
-  spec.add_development_dependency 'bundler', '~> 1.15'
-  spec.add_development_dependency 'rake', '~> 10.0'
-  spec.add_development_dependency 'minitest', '~> 5.0'
+  spec.add_development_dependency('bundler', '~> 2.1')
+  spec.add_development_dependency('minitest', '~> 5.0')
+  spec.add_development_dependency('rake', '~> 13.0')
 end

data/dev.yml

@@ -1,5 +1,5 @@
 up:
-  - ruby: 2.3.3
+  - ruby: 2.7.0
   - bundler
 
 commands:

data/examples/README.md

@@ -0,0 +1,21 @@
+# Examples
+
+**Note: If you're looking to bootstrap a new app, consider running `cli-kit new` instead of
+copy/pasting one of these.**
+
+## Full Example
+
+The full example lives in its own repository at https://github.com/Shopify/cli-kit-example.
+This is quite similar to the output of `cli-kit new`, but fleshed out a little bit more with
+a couple of commands.
+
+## Single-File starting point
+
+Maybe it appeals to you to start from a single file and grow, rather than generating framework.
+Check out the [`examples/single-file`](single-file) example.
+
+## Minimal example
+
+This example demonstrates the core of what `cli-kit` does very simply, but in general, shouldn't be
+used for anything other than quick hacks. It leaves out a few best practices that help CLI apps
+scale gracefully. Find it at [`examples/minimal`](minimal).

data/examples/minimal/example.rb

@@ -0,0 +1,22 @@
+#!/usr/bin/env ruby
+
+require 'cli/ui'
+require 'cli/kit'
+
+CLI::UI::StdoutRouter.enable
+
+include(CLI::Kit)
+
+registry = CommandRegistry.new(default: 'hello', contextual_resolver: nil)
+registry.add(Class.new(BaseCommand) do
+  def call(_args, _name)
+    puts 'hello, world!'
+  end
+end, 'hello')
+
+executor      = Executor.new(log_file: '/tmp/example.log')
+error_handler = ErrorHandler.new(log_file: '/tmp/example.log', exception_reporter: nil)
+resolver      = Resolver.new(tool_name: 'example', command_registry: registry)
+entry_point   = ->(args) { executor.call(*resolver.call(args)) }
+
+exit(error_handler.call { entry_point.call(ARGV.dup) }) if __FILE__ == $PROGRAM_NAME

data/examples/single-file/example.rb

@@ -0,0 +1,71 @@
+#!/usr/bin/env ruby
+
+require 'cli/ui'
+require 'cli/kit'
+
+CLI::UI::StdoutRouter.enable
+
+module Example
+  extend CLI::Kit::Autocall
+
+  TOOL_NAME = 'example'
+  ROOT      = File.expand_path('../..', __FILE__)
+  LOG_FILE  = '/tmp/example.log'
+
+  module Commands
+    extend CLI::Kit::Autocall
+
+    Registry = CLI::Kit::CommandRegistry.new(
+      default: 'hello',
+      contextual_resolver: nil
+    )
+
+    def self.register(const, cmd, path = nil, &block)
+      path ? autoload(const, path) : autocall(const, &block)
+      Registry.add(->() { const_get(const) }, cmd)
+    end
+
+    # register(:Hello, 'hello', 'a/b/hello')
+
+    register(:Hello, 'hello') do
+      Class.new(Example::Command) do
+        def call(_args, _name)
+          puts 'hello, world!'
+        end
+      end
+    end
+  end
+
+  autocall(:EntryPoint) do
+    Module.new do
+      def self.call(args)
+        cmd, command_name, args = Example::Resolver.call(args)
+        Example::Executor.call(cmd, command_name, args)
+      end
+    end
+  end
+
+  autocall(:Config)  { CLI::Kit::Config.new(tool_name: TOOL_NAME) }
+  autocall(:Command) { CLI::Kit::BaseCommand }
+
+  autocall(:Executor) { CLI::Kit::Executor.new(log_file: LOG_FILE) }
+  autocall(:Resolver) do
+    CLI::Kit::Resolver.new(
+      tool_name: TOOL_NAME,
+      command_registry: Example::Commands::Registry
+    )
+  end
+
+  autocall(:ErrorHandler) do
+    CLI::Kit::ErrorHandler.new(
+      log_file: LOG_FILE,
+      exception_reporter: nil
+    )
+  end
+end
+
+if __FILE__ == $PROGRAM_NAME
+  exit(Example::ErrorHandler.call do
+    Example::EntryPoint.call(ARGV.dup)
+  end)
+end

data/examples/todo-list/README.md

@@ -0,0 +1 @@
+Full example at https://github.com/Shopify/cli-kit-example

data/gen/lib/gen/commands/help.rb

@@ -4,15 +4,15 @@ module Gen
   module Commands
     class Help < Gen::Command
       def call(_args, _name)
-        puts CLI::UI.fmt("{{bold:Available commands}}")
-        puts ""
+        puts CLI::UI.fmt('{{bold:Available commands}}')
+        puts ''
 
         Gen::Commands::Registry.resolved_commands.each do |name, klass|
           puts CLI::UI.fmt("{{command:#{Gen::TOOL_NAME} #{name}}}")
-          if help = klass.help
+          if klass.respond_to?(:help) && (help = klass.help)
             puts CLI::UI.fmt(help)
           end
-          puts ""
+          puts ''
         end
       end
     end

data/gen/lib/gen/generator.rb

@@ -18,21 +18,20 @@ module Gen
     # false  -> delete file
     # string -> rename file before applying template substitutions
     VENDOR_TRANSLATIONS = {
-      'Gemfile'            => false,
-      'exe/__app__-gems'   => false,
+      'Gemfile' => false,
+      'exe/__app__-gems' => false,
       'exe/__app__-vendor' => 'exe/__app__',
-      'dev-gems.yml'       => false,
-      'dev-vendor.yml'     => 'dev.yml',
+      'dev-gems.yml' => false,
+      'dev-vendor.yml' => 'dev.yml',
     }.freeze
     private_constant :VENDOR_TRANSLATIONS
 
     BUNDLER_TRANSLATIONS = {
-      'bin'                => false,
-      'bin/update-deps'    => false,
-      'exe/__app__-gems'   => 'exe/__app__',
+      'bin/update-deps' => false,
+      'exe/__app__-gems' => 'exe/__app__',
       'exe/__app__-vendor' => false,
-      'dev-gems.yml'       => 'dev.yml',
-      'dev-vendor.yml'     => false,
+      'dev-gems.yml' => 'dev.yml',
+      'dev-vendor.yml' => false,
     }.freeze
     private_constant :BUNDLER_TRANSLATIONS
 
@@ -59,6 +58,9 @@ module Gen
     private
 
     def ask_vendor?
+      return true if ENV['DEPS'] == 'vendor'
+      return false if ENV['DEPS'] == 'bundler'
+
       vendor = nil
       CLI::UI::Frame.open('Configuration') do
         q = 'How would you like the application to consume {{command:cli-kit}} and {{command:cli-ui}}?'
@@ -114,7 +116,7 @@ module Gen
       out, stat = Open3.capture2e('git', '-C', dir, 'clone', "https://github.com/shopify/#{repo}")
       unless stat.success?
         STDERR.puts(out)
-        error("git clone failed")
+        error('git clone failed')
       end
     end