flo 0.0.2 → 0.0.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: b84be555cacd1fd27392d83cd39e89c19e9dafd4
-  data.tar.gz: 9cd073f4e4c9ab0da1ea2b816b2cb1e90a579441
+  metadata.gz: 0c4b34788a7d80192abd6ec7d302ebc9b0e44615
+  data.tar.gz: 26f726d4839283d43adc1a4fafd9a47464338b7e
 SHA512:
-  metadata.gz: 43b7d50133307857e6a656d5ef99b0c9b8c0e99030541b7c890086d3903e4ca6b4387ea624d060e17d02384b6d6b1e9c0dbad5c22d44809b4f324b920881fd43
-  data.tar.gz: e8ad9ceec8b76344fa641774919a41d38298f2c50d122668e64935175a0c4e61b657a95233746ee8c36cb8f491cd07919a5ec1fc7536f434981396a43664f31b
+  metadata.gz: c8b474dfc8872e4a04cd236c51837dda2668ef9f7d75bb405935f5cfd5998adcfe6068b09a38010a4f7b06d1cd5a37c99e3b67c246401a628836964a59d77a26
+  data.tar.gz: 38c4d9b143a55b62fbb9c71f86d53d7b62e19fc485c343e2b61cc67f640c54bb3fba302e2a42d5fca4161480d74c5a2170e852dd946417a69f5da389eb51d939

data/README.md

@@ -1,5 +1,5 @@
 # Flo
-[![Code Climate](https://codeclimate.com/github/codeclimate/codeclimate/badges/gpa.svg)](https://codeclimate.com/github/codeclimate/codeclimate) [![Build Status](https://semaphoreci.com/api/v1/justinpowers/flo/branches/master/shields_badge.svg)](https://semaphoreci.com/justinpowers/flo)
+[![Gem Version](https://badge.fury.io/rb/flo.svg)](https://badge.fury.io/rb/flo) [![Code Climate](https://codeclimate.com/github/salesforce/flo/badges/gpa.svg)](https://codeclimate.com/github/salesforce/flo) [![Test Coverage](https://codeclimate.com/github/salesforce/flo/badges/coverage.svg)](https://codeclimate.com/github/salesforce/flo/coverage) [![Build Status](https://semaphoreci.com/api/v1/justinpowers/flo/branches/master/shields_badge.svg)](https://semaphoreci.com/justinpowers/flo) [![Inline docs](http://inch-ci.org/github/salesforce/flo.svg?branch=master)](http://inch-ci.org/github/salesforce/flo)
 
 
 Flo is a local workflow automation tool that helps you get things done.  This gem contains the core functionality for Flo, plugins for interacting with various systems can be found in separate provider gems.
@@ -23,14 +23,23 @@ $ gem install flo
 ```
 
 ## Documentation
-https://www.rubydoc.info/github/salesforce/flo/
+http://www.rubydoc.info/github/salesforce/flo/
 
 ## Usage
 
 ### Command line usage
 
-COMING SOON!
-A command line parser has not yet been added.  If you require a script that can be invoked from the command line, you can create a ruby script that creates and runs a `Flo::Runner` instance.  See [Ruby script usage](#Ruby_script_usage) for more details.
+If you have a `.flo` configuration file (See [.flo configuration file](#flo-configuration-file)), in your current working directory and/or your home directory, flo will parse your configuration file(s) and generate CLI commands for you.  To list out the possible commands, use
+
+```bash
+flo help
+```
+
+You can also see the usage and options for specific commands:
+
+```bash
+flo help <command>
+```
 
 ### Ruby script usage
 
@@ -45,7 +54,7 @@ runner = Flo::Runner.new
 runner.load_config_file(File.join(__dir__,'.flo'))
 
 # Run the something:useful command defined in the .flo file
-response = runner.execute([:something, :useful], id: '123')
+response = runner.execute('something:useful', id: '123')
 ```
 
 
@@ -73,7 +82,7 @@ You can register any number of commands.  Commands are namespaced to make it eas
 # Registers a command for starting a feature - feature:start.  This command has
 # one required argument: 'feature_name'.  Note that in order for this to work,
 # you will need to declare the git_flo provider in the config section.
-register_command([:feature, :start]) do |feature_name: nil|
+register_command('feature:start') do |feature_name: nil|
 
   # During command execution, perform the :check_out_or_create_branch method on
   # the git_flo provider, passing in the :from and :name arguments
@@ -88,6 +97,7 @@ end
 3. Commit your changes (`git commit -am 'Add some feature'`)
 4. Push to the branch (`git push origin my-new-feature`)
 5. Create new Pull Request
+6. If this is your first contribution, you will need Accept the Contributor License Agreement.  You can follow the link in the pull request 'checks' section to do so.
 
 ## License
 

data/bin/flo

@@ -0,0 +1,12 @@
+#!/usr/bin/env ruby
+
+# Copyright © 2017, Salesforce.com, Inc.
+# All Rights Reserved.
+# Licensed under the BSD 3-Clause license.
+# For full license text, see LICENSE.txt file in the repo root or https://opensource.org/licenses/BSD-3-Clause
+
+$LOAD_PATH.unshift File.expand_path('../../lib', __FILE__)
+require 'flo'
+require 'flo/cli'
+
+Flo::Cli.new.call(ARGV)

data/flo.gemspec

@@ -9,24 +9,29 @@ $LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
 require 'flo/version'
 
 Gem::Specification.new do |spec|
-  spec.name          = "flo"
+  spec.name          = 'flo'
   spec.version       = Flo::VERSION
-  spec.authors       = ["Justin Powers"]
-  spec.email         = ["justinspowers@gmail.com"]
+  spec.authors       = ['Justin Powers']
+  spec.email         = ['justinspowers@gmail.com']
   spec.summary       = %q{Simple developer workflow automation}
   spec.description   = %q{Flo is a local workflow automation tool that helps you get things done.  This gem contains the core functionality for Flo, plugins for interacting with various systems can be found in separate provider gems.}
-  spec.homepage      = "https://github.com/salesforce/flo"
-  spec.license       = "BSD-3-Clause"
+  spec.homepage      = 'https://github.com/salesforce/flo'
+  spec.license       = 'BSD-3-Clause'
 
+  spec.executables   << 'flo'
   spec.files         = `git ls-files -z`.split("\x0")
   spec.test_files    = spec.files.grep(%r{^test/})
-  spec.require_paths = ["lib"]
+  spec.require_paths = ['lib']
 
-  spec.add_dependency "cleanroom"
+  spec.add_dependency 'cleanroom'
+  spec.add_dependency 'gpgme'
+  spec.add_dependency 'cri'
 
-  spec.add_development_dependency "bundler", "~> 1.5"
-  spec.add_development_dependency "rake"
-  spec.add_development_dependency "minitest"
-  spec.add_development_dependency "pry"
-  spec.add_development_dependency "simplecov"
+  spec.add_development_dependency 'bundler', '~> 1.5'
+  spec.add_development_dependency 'rake'
+  spec.add_development_dependency 'minitest'
+  spec.add_development_dependency 'minitest-proveit'
+  spec.add_development_dependency 'pry'
+  spec.add_development_dependency 'simplecov'
+  spec.add_development_dependency 'codeclimate-test-reporter'
 end

data/lib/flo/cli.rb

@@ -0,0 +1,76 @@
+# Copyright © 2017, Salesforce.com, Inc.
+# All Rights Reserved.
+# Licensed under the BSD 3-Clause license.
+# For full license text, see LICENSE.txt file in the repo root or https://opensource.org/licenses/BSD-3-Clause
+
+require 'cri'
+
+module Flo
+
+  # Builds the command line parser and executes Flo::Runner using the commands supplied.
+  # In general you should be able to create a new instance and then pass in ARGV directly
+  # into {#call}.
+  class Cli
+
+    # Creates a new CLI runner instance.
+    # @option opts [Class] runner_class (Runner) Class of the runner object dependency
+    def initialize(opts={})
+      @runner_class = opts[:runner_class] || Runner
+    end
+
+    # Runs a command using args directly from ARGV.
+    # @param argv [Array<String>] An array of strings.  Typically you would pass in ARGV directly.
+    #   The first value should be the name of the command
+    #
+    def call(argv)
+      generate_commands.run(argv)
+    end
+
+    private
+
+    attr_reader :runner_class
+
+    def generate_commands
+      flo_runner = runner_class.new
+      flo_runner.load_default_config_files
+
+      flo_runner.commands.each do |cmd_name, cmd|
+
+        main_command.define_command do
+          options = cmd[:command].required_parameters
+
+          unless cmd[:command].optional_parameters.empty?
+            options << '[options]'
+
+            cmd[:command].optional_parameters.each do |param|
+              optional(nil, param, param.to_s.tr('_', ' '))
+            end
+          end
+
+          name(cmd_name)
+          usage("#{cmd_name} #{options.join(' ')}")
+          summary(cmd[:summary])
+          description(cmd[:description])
+
+          run do |opts, arguments, command|
+            flo_runner.execute(command.name, arguments.dup.push(opts))
+          end
+        end
+      end
+
+      main_command
+    end
+
+    def main_command
+      @main_command ||= Cri::Command.new_basic_root.modify do
+        name        'flo'
+        usage       'flo [command]'
+        summary     'Local workflow automation'
+        description 'Use `flo help [command]` for usage on individual commands'
+
+        default_subcommand 'help'
+      end
+    end
+
+  end
+end

data/lib/flo/command.rb

@@ -87,11 +87,32 @@ module Flo
       end.last
     end
 
+    # Returns a list of any required parameters
+    #
+    # Required parameters are generated automatically by inspecting the required
+    # parameters for the definition lambda
+    # @return [Array<Symbol>] An array of symbols representing required parameters
+    #
+    def required_parameters
+      definition_lambda.parameters.select { |key,_value| key == :req }.map { |_key,value| value }
+    end
+
+
+    # Returns a list of any optional parameters
+    #
+    # Optional parameters are generated automatically by inspecting the optional
+    # parameters for the definition lambda
+    # @return [Array<Symbol>] An array of symbols representing optional parameters
+    #
+    def optional_parameters
+      definition_lambda.parameters.select { |key,_value| key == :key }.map { |_key,value| value }
+    end
+
     private
 
     attr_reader :tasks, :definition_lambda, :providers, :state_class
 
-    def evaluate_command_definition(*args)
+    def evaluate_command_definition(args)
       cleanroom.instance_exec(*args, &definition_lambda)
     end
 

data/lib/flo/command_collection.rb

@@ -3,22 +3,32 @@
 # Licensed under the BSD 3-Clause license.
 # For full license text, see LICENSE.txt file in the repo root or https://opensource.org/licenses/BSD-3-Clause
 
+require 'forwardable'
+require 'flo/error'
+
 module Flo
-  CommandNotDefinedError = Class.new(StandardError)
+
+  CommandNotDefinedError = Class.new(Flo::Error)
+
+  # A collection of commands.  Behaves like a Hash, except that fetching a key that does
+  # not exist raises an error
   class CommandCollection
+    extend Forwardable
+    def_delegators :@commands, :each, :[]=
 
     def initialize
       @commands = {}
     end
 
-    def [](*key)
+    # Returns the value corresponding to the key.  Identical to accessing Hash values, except
+    # that fetching a value that does not exist raises an error
+    # @param key [String] Name of the command
+    # @raises Flo::CommandNotDefinedError if the command does not exist
+    #
+    def [](key)
       raise CommandNotDefinedError.new("#{key} command is not defined") unless @commands.has_key?(key)
       @commands[key]
     end
 
-    def []=(*key, command)
-      @commands[key] = command
-    end
-
   end
 end

data/lib/flo/config.rb

@@ -3,14 +3,30 @@
 # Licensed under the BSD 3-Clause license.
 # For full license text, see LICENSE.txt file in the repo root or https://opensource.org/licenses/BSD-3-Clause
 
+require 'flo/cred_store/yaml_store'
+
 module Flo
-  MissingRequireError = Class.new(StandardError)
+  MissingRequireError = Class.new(Flo::Error)
 
   # Instantiates and stores providers for use in command definitions
   #
   # @attr_reader providers [Hash] Hash of provider instances
   #
   class Config
+
+    # A placeholder for credentials that can be evaluated at a later time
+    class LazyCreds
+
+      # Returns a lambda that takes a credential store for a specific provider as an argument.
+      # This prevents providers from accessing the credentials for another provider
+      # @param key [Symbol,String]
+      # @return [lambda]
+      def [](key)
+        lambda { |cred_store| cred_store[key] }
+      end
+    end
+
+    attr_writer :cred_store
     attr_reader :providers
 
     def initialize
@@ -24,7 +40,20 @@ module Flo
     # accepts a block
     #
     def provider(provider_sym, options={}, &blk)
-      @providers[provider_sym] = provider_class(provider_sym).new(options, &blk)
+      provider = provider_class(provider_sym).new(options, &blk)
+      provider.cred_store = cred_store.credentials_for(provider_sym)
+      @providers[provider_sym] = provider
+    end
+
+    def cred_store
+      @cred_store ||= Flo::CredStore::YamlStore.new
+    end
+
+    # Returns an object that responds to [], but instead of returning a value, returns
+    # a lambda that can be evaluated later in the context of the credentials for the provider
+    # @return [LazyCred]
+    def creds
+      LazyCreds.new
     end
 
     private
@@ -33,7 +62,7 @@ module Flo
       klass = camel_case(provider_sym.to_s)
       klass_name = "Flo::Provider::#{klass}"
       Object.const_get(klass_name)
-    rescue NameError => e
+    rescue NameError
       raise MissingRequireError.new("#{klass_name} is not loaded.  Please require the library before use")
     end
 

data/lib/flo/cred_store/creds.rb

@@ -0,0 +1,27 @@
+# Copyright © 2017, Salesforce.com, Inc.
+# All Rights Reserved.
+# Licensed under the BSD 3-Clause license.
+# For full license text, see LICENSE.txt file in the repo root or https://opensource.org/licenses/BSD-3-Clause
+
+module Flo
+  MissingCredentialError = Class.new(Flo::Error)
+
+  module CredStore
+    class Creds
+
+      def initialize(credentials)
+        @credentials = credentials
+      end
+
+      # Returns the credential referenced by the key provided
+      # @param key [Symbol, String]
+      # @raises Flo::MissingCredentialError if key does not exist
+      #
+      def [](key)
+        raise Flo::MissingCredentialError unless @credentials.key?(key)
+
+        @credentials[key]
+      end
+    end
+  end
+end

data/lib/flo/cred_store/pw_protected_store.rb

@@ -0,0 +1,59 @@
+# Copyright © 2017, Salesforce.com, Inc.
+# All Rights Reserved.
+# Licensed under the BSD 3-Clause license.
+# For full license text, see LICENSE.txt file in the repo root or https://opensource.org/licenses/BSD-3-Clause
+
+module Flo
+  module CredStore
+    class PwProtectedStore
+
+      attr_writer :cred_file
+
+      def initialize(opts={})
+        @password = opts[:password] # If nil, should prompt interactively
+        @cred_file_location = opts[:cred_file_location]
+      end
+
+      # Decrypts the credentials file and returns the credentials for the requested provider
+      # @param provider_sym [Symbol]
+      # @return [Flo::CredStore::Creds]
+      #
+      def credentials_for(provider_sym)
+        Flo::CredStore::Creds.new(full_credentials_hash[provider_sym])
+      end
+
+      # Convenience method for producing an encrypted version of a file.  This only returns
+      # the encrypted version as a string, you will have to save it yourself if desired
+      # @param file_location [String]
+      # @return [String]
+      def encrypt_file(file_location)
+        crypto.encrypt(File.open(file_location)).to_s
+      end
+
+      def cred_file
+        @cred_file ||= File.new(@cred_file_location || File.join(Dir.home, '.flo_creds.yml.gpg'))
+      end
+
+      # Remove password from inspect output
+      def inspect
+        "#<Flo::CredStore::PwProtectedStore:#{object_id} @cred_file=#{cred_file.inspect}>"
+      end
+
+      private
+
+      attr_reader :password
+
+      def decrypted_file
+        crypto.decrypt(cred_file)
+      end
+
+      def full_credentials_hash
+        @full_credentials_hash ||= YAML.load(decrypted_file.read) || {}
+      end
+
+      def crypto
+        GPGME::Crypto.new(password: @password, symmetric: true)
+      end
+    end
+  end
+end

data/lib/flo/cred_store/yaml_store.rb

@@ -0,0 +1,36 @@
+# Copyright © 2017, Salesforce.com, Inc.
+# All Rights Reserved.
+# Licensed under the BSD 3-Clause license.
+# For full license text, see LICENSE.txt file in the repo root or https://opensource.org/licenses/BSD-3-Clause
+
+require 'yaml'
+require 'flo/error'
+require 'flo/cred_store/creds'
+
+module Flo
+
+  MissingProviderError = Class.new(Flo::Error)
+
+  module CredStore
+    class YamlStore
+
+      def initialize(location=nil)
+        @location = location || File.join(Dir.home, '.flo_creds.yml')
+      end
+
+      # Returns the credentials for the requested provider
+      # @param provider_sym [Symbol]
+      # @return [Flo::CredStore::Creds]
+      #
+      def credentials_for(provider_sym)
+        Flo::CredStore::Creds.new(full_credentials_hash[provider_sym])
+      end
+
+      private
+
+      def full_credentials_hash
+        @full_credentials_hash ||= YAML.load(File.read(@location)) || {}
+      end
+    end
+  end
+end

data/lib/flo/error.rb

@@ -0,0 +1,9 @@
+# Copyright © 2017, Salesforce.com, Inc.
+# All Rights Reserved.
+# Licensed under the BSD 3-Clause license.
+# For full license text, see LICENSE.txt file in the repo root or https://opensource.org/licenses/BSD-3-Clause
+
+module Flo
+
+  Error = Class.new(StandardError)
+end

data/lib/flo/provider/base.rb

@@ -0,0 +1,62 @@
+# Copyright © 2017, Salesforce.com, Inc.
+# All Rights Reserved.
+# Licensed under the BSD 3-Clause license.
+# For full license text, see LICENSE.txt file in the repo root or https://opensource.org/licenses/BSD-3-Clause
+
+module Flo
+  module Provider
+    MissingOptionError = Class.new(StandardError)
+    OptionDefinition = Struct.new(:default, :required)
+
+    # @abstract Subclass and use {.option} to declare initialize options
+    # A base provider class that all custom providers should inherit from.
+    #
+    class Base
+
+      attr_writer :cred_store
+
+      # Creates an instance of a provider
+      # @param opts [Hash] Arbitrary array of options defined by the provider
+      #   using the {.option} method
+      # @raise [MissingOptionError] if a required option is not provided.  Error
+      #   message will state which options are missing.
+      #
+      def initialize(opts={})
+        # @options = allow_whitelisted(opts, @@option_keys)
+        @options = {}
+        self.class.option_keys.each do |key, definition|
+          @options[key] = opts.fetch(key, definition.default)
+        end
+
+        missing_required = self.class.option_keys.select {|_k,v| v.required }.keys - @options.select { |_k,v| !v.nil? }.keys
+        unless missing_required.empty?
+          raise MissingOptionError.new("#{self.class.name} invoked without required options: #{missing_required.join(' ')}")
+        end
+      end
+
+      # Declare an option to be passed in when declaring the provider in the
+      # .flo file
+      # @param name [Symbol] The name of the option
+      # @param default Default value for the option if none is provided
+      # @option args [Boolean] :required (false) Whether the option is required.
+      #   A MissingOptionError will be raised if a provider is instantiated
+      #   without a required argument
+      #
+      def self.option(name, default=nil, args={})
+        option_keys[name] = OptionDefinition.new(default, args[:required] == true)
+      end
+
+      # Hash of option definitions.  Add to this hash using the {.option}
+      # method.
+      #
+      # @return [Hash{Symbol => OptionDefiniton}]
+      def self.option_keys
+        @option_keys ||= {}
+      end
+
+      private
+
+      attr_reader :options
+    end
+  end
+end

data/lib/flo/provider/developer.rb

@@ -3,16 +3,15 @@
 # Licensed under the BSD 3-Clause license.
 # For full license text, see LICENSE.txt file in the repo root or https://opensource.org/licenses/BSD-3-Clause
 
+require 'flo/provider/base'
 require 'ostruct'
 
 module Flo
   module Provider
     Response = Struct.new(:success?)
-    class Developer
+    class Developer < Flo::Provider::Base
 
-      def initialize(options={})
-
-      end
+      option :password, nil, required: false
 
       def is_successful(opts={})
         success = opts[:success].nil? ? true : opts[:success]
@@ -23,9 +22,8 @@ module Flo
         true
       end
 
-      def echo(opts={})
-        puts opts.inspect
-        Flo::Provider::Response.new(true)
+      def has_option(opts={})
+        Flo::Provider::Response.new(options.include?(opts[:option]))
       end
     end
   end

data/lib/flo/runner.rb

@@ -3,7 +3,6 @@
 # Licensed under the BSD 3-Clause license.
 # For full license text, see LICENSE.txt file in the repo root or https://opensource.org/licenses/BSD-3-Clause
 
-require 'flo'
 require 'flo/command'
 require 'flo/command_collection'
 require 'flo/state'
@@ -48,14 +47,28 @@ module Flo
       evaluate_file(config_file)
     end
 
+    # Open and parse any available config files, in the following order:
+    # * ENV['FLO_CONFIG_FILE'] # Allows the addition of custom files
+    # * ./.flo
+    # * ~/.flo
+    # See {#load_config_file}
+    #
+    def load_default_config_files
+      [ENV['FLO_CONFIG_FILE'], File.join(Dir.pwd, '.flo'), File.join(Dir.home, '.flo')].compact.each do |file|
+        if File.exist?(file)
+          self.load_config_file(file)
+        end
+      end
+    end
+
     # Executes the command specified, with the arguments specified
     # @param command_namespace [Array<Symbol>] An array containing the name of
     #   the command as a symbol, including the namespace.  For example, the
     #   command "issue submit" would become [:issue, :submit]
-    # @param args={} [Hash] Options that will get passed to the command
+    # @param args=[] [Array] Options that will get passed to the command
     #
-    def execute(command_namespace, args={})
-      commands[command_namespace].call(args)
+    def execute(command_namespace, args=[])
+      commands[command_namespace][:command].call(args)
     end
 
     # @api dsl
@@ -76,13 +89,15 @@ module Flo
     # DSL method: Creates and defines a {Command}, adding it to the command collection.
     # Definition for the command should happen inside of the required block.
     # See {Command} for methods available within the block.
-    # @param command_namespace [Array<Symbol>] Array of symbols representing the
-    #   command including the namespace
-    # @yield [args*]The block containing the definition for the command.
+    # @param command_namespace [String] name of the command
+    # @option opts [String] :summary Summary of the command
+    # @option opts [String] :description Detailed description of the command
+    # @yield [args*] The block containing the definition for the command.
     #   Arguments passed into {#execute} are available within the block
     #
-    def register_command(command_namespace, &blk)
-      commands[command_namespace] = command_class.new(providers: config.providers, &blk)
+    def register_command(command_namespace, opts={}, &blk)
+      opts[:command] = command_class.new(providers: config.providers, &blk)
+      commands[command_namespace] = opts
     end
     expose :register_command