hammer_cli 0.0.4

data/LICENSE

@@ -0,0 +1,5 @@
+This program and entire repository is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or any later version.
+
+This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
+
+You should have received a copy of the GNU General Public License along with this program. If not, see http://www.gnu.org/licenses/.

data/README.md

@@ -0,0 +1,105 @@
+Hammer - the CLI tool for foreman
+=================================
+
+![Design draft](doc/design.png)
+
+As the diagram shows, the CLI consist of almost generic framework (shell-like environment, autocompletion, command help text, option evaluation and command invocation) and set of plugins defining the actual commands. This setup is flexible and allows us to easily install different sets of commands for different products. The plugins are independant and can implement any action as an command, so that besides commands calling Foreman API you can have commands calling varius admin tasks, etc.
+
+
+The CLI has
+
+ - Git-like subcomands
+ - system shell autocompletion for commands and options
+ - shell-like environment with autocompletion and history where the commands can be run directly
+ - commands extensible via plugins
+ - been implemented in Ruby
+ 
+
+If you are interested you can help us by sending patches or filing bugs and feature requests (there is CLI catgory in Redmine)
+
+
+How to run
+----------
+
+The work is in progress and there are still no builds ready, but instaling from sources is easy. You will need rake, bundler.
+Clone and install CLI core
+
+    $ git clone git@github.com:theforeman/hammer-cli.git
+    $ cd hammer-cli
+    $ rake install
+    $ cd ..
+
+
+clone plugin with foreman commands
+
+    $ git clone git@github.com:theforeman/hammer-cli-foreman.git
+    $ cd hammer-cli-foreman
+    $ rake install
+    $ cd ..
+    
+and configure. Configuration is by default looked for in ~/.foreman/ or in /etc/foreman/. 
+Optionally you can put your configuration in ./config/ or point hammer 
+to some other location using -c CONF_FILE option
+
+You can start with config file template we created for you and update it to suit your needs. E.g.:
+
+    $ cp hammer-cli/config/cli_config.template.yaml ~/.foreman/cli_config.yml
+
+and run 
+
+    $ hammer -h
+    Usage:
+        hammer [OPTIONS] SUBCOMMAND [ARG] ...
+
+    Parameters:
+        SUBCOMMAND                    subcommand
+        [ARG] ...                     subcommand arguments
+
+    Subcommands:
+        shell                         Interactive Shell
+        architecture                  Manipulate Foreman's architectures.
+        compute_resource              Manipulate Foreman's architectures.
+        domain                        Manipulate Foreman's domains.
+        organization                  Manipulate Foreman's organizations.
+        subnet                        Manipulate Foreman's subnets.
+        user                          Manipulate Foreman's users.
+
+    Options:
+        -v, --verbose                 be verbose
+        -u, --username USERNAME       username to access the remote system
+        -p, --password PASSWORD       password to access the remote system
+        --version                     show version
+        --autocomplete LINE           Get list of possible endings
+        -h, --help                    print help
+
+
+Autocompletion
+--------------
+
+It is necessary to copy script hammer_cli_complete to the bash_completion.d directory. 
+
+    $ sudo cp hammer-cli/hammer_cli_complete /etc/bash_completion.d/
+
+Then in new shell the completion should work.
+
+
+How to test
+------------
+
+Development of almost all the code was test driven.
+
+    $ bundle install
+    $ bundle exec "rake test"
+
+should work in any of the cli related repos. Generated coverage reports are stored in ./coverage directory.
+
+License
+-------
+
+This project is licensed under the GPLv3+.
+
+
+Acknowledgements
+----------------
+
+Thanks to Brian Gupta for the initial work and a great name.

data/bin/hammer

@@ -0,0 +1,53 @@
+#! /usr/bin/env ruby
+
+require 'rubygems'
+require 'clamp'
+
+# create fake command instance to use some global args before we start
+class PreParser < Clamp::Command
+  option ["-v", "--verbose"], :flag, "be verbose"
+  option ["-c", "--config"], "CFG_FILE", "path to custom config file"
+end
+
+preparser = PreParser.new File.basename($0), {}
+begin
+  preparser.parse ARGV
+rescue
+end
+
+# load user's settings
+require 'hammer_cli/settings'
+
+CFG_PATH = ['./config/cli_config.yml', '~/.foreman/cli_config.yml', '/etc/foreman/cli_config.yml']
+
+if preparser.config
+  CFG_PATH.unshift preparser.config
+end
+
+HammerCLI::Settings.load_from_file CFG_PATH
+
+# setup logging
+require 'hammer_cli/logger'
+logger = Logging.logger['Init']
+
+if preparser.verbose?
+  root_logger = Logging.logger.root
+  root_logger.appenders = root_logger.appenders << ::Logging.appenders.stderr(:layout => HammerCLI::Logger::COLOR_LAYOUT)
+end
+
+# log which config was loaded (now when we have logging)
+HammerCLI::Settings.path_history.each do |path|
+  logger.info "Configuration from the file #{path} has been loaded"
+end
+
+# load hammer core
+require 'hammer_cli'
+
+# load modules set in config
+modules = HammerCLI::Settings[:modules] || []
+modules.each do |m| 
+  require m 
+  logger.info "Extension module #{m} loaded"
+end
+
+exit HammerCLI::MainCommand.run || 0

data/config/cli_config.template.yml

@@ -0,0 +1,14 @@
+:modules:
+#    - hammer_cli_foreman
+#    - hammer_cli_katello_bridge
+
+:host: 'https://localhost/'
+:username: 'admin'
+:password: 'changeme'
+
+# :watch_plain: true disables color output of logger.watch in Clamp commands
+:watch_plain: false
+
+#:log_dir: '/var/log/foreman'
+:log_dir: '~/.foreman/log'
+:log_level: 'error'

data/doc/design.uml

@@ -0,0 +1,24 @@
+@startuml
+
+
+[Foreman API] as FAPI
+FAPI -up-> [Foreman Server]
+[Foreman Commands Plugin] as FCP
+FCP -up-> FAPI
+
+[Katello CLI via system call] as KCLI
+KCLI -up-> [Katello Server]
+[Katello Commands Plugin] as KCP
+KCP -up-> KCLI
+
+package "CLI Framework" {
+  () "Command Plugins" as CP
+  [Shell]
+  [Autocompletion]
+}
+
+CP -up-> [Other Commands Plugin(s)]
+CP -up-> FCP
+CP -up-> KCP
+
+@enduml

data/hammer_cli_complete

@@ -0,0 +1,13 @@
+#
+# Hammer CLI bash completion script
+#
+# vim:ts=2:sw=2:et:
+#
+
+_hammer() {
+  COMPREPLY=($(hammer --autocomplete "${COMP_WORDS[*]}"))
+  return 0
+}
+
+complete -F _hammer hammer
+

data/lib/hammer_cli/abstract.rb

@@ -0,0 +1,95 @@
+require 'hammer_cli/autocompletion'
+require 'hammer_cli/exception_handler'
+require 'hammer_cli/logger_watch'
+require 'clamp'
+require 'logging'
+
+module HammerCLI
+
+  class AbstractCommand < Clamp::Command
+
+    extend Autocompletion
+    class << self
+      attr_accessor :validation_block
+    end
+
+    def run(arguments)
+      exit_code = super(arguments)
+      raise "exit code must be integer" unless exit_code.is_a? Integer
+      return exit_code
+    rescue => e
+      # do not catch Clamp errors
+      raise if e.class <= Clamp::UsageError || e.class <= Clamp::HelpWanted
+      handle_exception e
+    end
+
+    def parse(arguments)
+      super(arguments)
+      validate_options
+      logger.info "Called with options: %s" % options.inspect
+    rescue HammerCLI::Validator::ValidationError => e
+      signal_usage_error e.message
+    end
+
+    def execute
+      HammerCLI::EX_OK
+    end
+
+    def self.validate_options &block
+      self.validation_block = block
+    end
+
+    def validate_options
+      validator.run &self.class.validation_block if self.class.validation_block
+    end
+
+
+    def output
+      @output ||= HammerCLI::Output::Output.new
+    end
+
+    def exception_handler
+      @exception_handler ||= exception_handler_class.new :output => output
+    end
+
+    protected
+
+    def logger name=self.class
+      logger = Logging.logger[name]
+      logger.extend(HammerCLI::Logger::Watch) if not logger.respond_to? :watch
+      logger
+    end
+
+    def validator
+      options = self.class.recognised_options.collect{|opt| opt.of(self)}
+      @validator ||= HammerCLI::Validator.new(options)
+    end
+
+    def handle_exception e
+      exception_handler.handle_exception(e)
+    end
+
+    def exception_handler_class
+      #search for exception handler class in parent modules/classes
+      module_list = self.class.name.to_s.split('::').inject([Object]) do |mod, class_name|
+        mod << mod[-1].const_get(class_name)
+      end
+      module_list.reverse.each do |mod|
+        return mod.send(:exception_handler_class) if mod.respond_to? :exception_handler_class
+      end
+      return HammerCLI::ExceptionHandler
+    end
+
+    def all_options
+      self.class.recognised_options.inject({}) do |h, opt|
+        h[opt.attribute_name] = send(opt.read_method)
+        h
+      end
+    end
+
+    def options
+      all_options.reject {|key, value| value.nil? }
+    end
+
+  end
+end

data/lib/hammer_cli/apipie/command.rb

@@ -0,0 +1,75 @@
+require File.join(File.dirname(__FILE__), 'options')
+require File.join(File.dirname(__FILE__), 'resource')
+
+module HammerCLI::Apipie
+
+  class Command < HammerCLI::AbstractCommand
+
+    include HammerCLI::Apipie::Resource
+    include HammerCLI::Apipie::Options
+
+    def initialize(*args)
+      setup_identifier_options
+      super(*args)
+    end
+
+    def setup_identifier_options
+      self.class.identifier_option(:id, "resource id")
+      self.class.identifier_option(:name, "resource name")
+      self.class.identifier_option(:label, "resource label")
+    end
+
+    def self.identifiers *keys
+      @identifiers ||= {}
+      keys.each do |key|
+        if key.is_a? Hash
+          @identifiers.merge!(key)
+        else
+          @identifiers.update(key => key)
+        end
+      end
+    end
+
+    def validate_options
+      super
+      validator.any(*self.class.declared_identifiers.values).required
+    end
+
+    protected
+
+    def get_identifier
+      self.class.declared_identifiers.keys.each do |identifier|
+        value = find_option("--"+identifier.to_s).of(self).read
+        return [value, identifier] if value
+      end
+      [nil, nil]
+    end
+
+    def self.identifier? key
+      if @identifiers
+        return true if @identifiers.keys.include? key
+      else
+        return true if superclass.respond_to?(:identifier?, true) and superclass.identifier?(key)
+      end
+      return false
+    end
+
+    def self.declared_identifiers
+      if @identifiers
+        return @identifiers
+      elsif superclass.respond_to?(:declared_identifiers, true)
+        superclass.declared_identifiers
+      else
+        {}
+      end
+    end
+
+    private
+
+    def self.identifier_option(name, desc)
+      attr_name = declared_identifiers[name]
+      option "--"+name.to_s, name.to_s.upcase, desc, :attribute_name => attr_name if self.identifier? name
+    end
+
+  end
+end

data/lib/hammer_cli/apipie/options.rb

@@ -0,0 +1,97 @@
+require 'hammer_cli/option_formatters'
+
+module HammerCLI::Apipie
+  module Options
+
+    def self.included(base)
+      base.extend(ClassMethods)
+    end
+
+    def all_method_options
+      method_options_for_params(self.class.method_doc["params"], true)
+    end
+
+    def method_options
+      method_options_for_params(self.class.method_doc["params"], false)
+    end
+
+    def method_options_for_params params, include_nil=true
+      opts = {}
+      params.each do |p|
+        if p["expected_type"] == "hash"
+          opts[p["name"]] = method_options_for_params(p["params"], include_nil)
+        elsif respond_to?(p["name"], true)
+          opts[p["name"]] = send(p["name"])
+        else
+          opts[p["name"]] = nil
+        end
+      end
+      opts.reject! {|key, value| value.nil? } unless include_nil
+      opts
+    end
+
+    module ClassMethods
+
+      def apipie_options options={}
+        raise "Specify apipie resource first." unless resource_defined?
+
+        filter = options[:without] || []
+        filter = Array(filter)
+
+        options_for_params(method_doc["params"], filter)
+      end
+
+      protected
+
+      def options_for_params params, filter
+        params.each do |p|
+          next if filter.include? p["name"].to_s or filter.include? p["name"].to_sym
+          if p["expected_type"] == "hash"
+            options_for_params(p["params"], filter)
+          else
+            create_option p
+          end
+        end
+      end
+
+      def create_option param
+        option(
+          option_switches(param),
+          option_type(param),
+          option_desc(param),
+          option_opts(param),
+          &option_formatter(param)
+        )
+      end
+
+      def option_switches param
+        '--' + param["name"].gsub('_', '-')
+      end
+
+      def option_type param
+        param["name"].upcase.gsub('-', '_')
+      end
+
+      def option_desc param
+        desc = param["description"].gsub(/<\/?[^>]+?>/, "")
+        return " " if desc.empty?
+        return desc
+      end
+
+      def option_opts param
+        opts = {}
+        opts[:required] = true if param["required"]
+        return opts
+      end
+
+      def option_formatter param
+        # FIXME: There is a bug in apipie, it does not produce correct expected type for Arrays
+        # When it's fixed, we should test param["expected_type"] == "array"
+        if param["validator"].include? "Array"
+          HammerCLI::OptionFormatters.method(:list)
+        end
+      end
+
+    end
+  end
+end

data/lib/hammer_cli/apipie/read_command.rb

@@ -0,0 +1,58 @@
+require 'hammer_cli/output/dsl'
+
+module HammerCLI::Apipie
+
+  class ReadCommand < Command
+
+      def self.output definition=nil, &block
+        dsl = HammerCLI::Output::Dsl.new
+        dsl.build &block
+
+        output_definition.append definition.fields unless definition.nil?
+        output_definition.append dsl.fields
+      end
+
+      def self.heading heading=nil
+        @heading = heading if heading
+        @heading
+      end
+
+      def output_definition
+        self.class.output_definition
+      end
+
+      def self.output_definition
+        @output_definition ||= HammerCLI::Output::Definition.new
+        @output_definition
+      end
+
+      def output
+        @output ||= HammerCLI::Output::Output.new :definition => output_definition
+      end
+
+      def execute
+        d = retrieve_data
+        logger.watch "Retrieved data: ", d
+        print_data d
+        return HammerCLI::EX_OK
+      end
+
+      protected
+      def retrieve_data
+        raise "resource or action not defined" unless self.class.resource_defined?
+        resource.send(action, request_params)[0]
+      end
+
+      def print_data(records)
+        output.print_records(records, self.class.heading)
+      end
+
+      def request_params
+        method_options
+      end
+
+  end
+
+end
+
+

data/lib/hammer_cli/apipie/resource.rb

@@ -0,0 +1,54 @@
+module HammerCLI::Apipie
+  module Resource
+
+    def self.included(base)
+      base.extend(ClassMethods)
+    end
+
+    def resource
+      @resource ||= self.class.resource.new resource_config
+      @resource
+    end
+
+    def action
+      self.class.action
+    end
+
+    def resource_config
+      config = {}
+      config[:base_url] = HammerCLI::Settings[:host]
+      config[:username] = context[:username] || HammerCLI::Settings[:username] || ENV['FOREMAN_USERNAME']
+      config[:password] = context[:password] || HammerCLI::Settings[:password] || ENV['FOREMAN_PASSWORD']
+      config
+    end
+
+    module ClassMethods
+
+
+      def resource resource=nil, action=nil
+        @api_resource = resource unless resource.nil?
+        @api_action = action unless action.nil?
+        return @api_resource if @api_resource
+        return superclass.resource
+      end
+
+      def action action=nil
+        @api_action = action unless action.nil?
+        @api_action
+      end
+
+      def method_doc
+        @api_resource.doc["methods"].each do |method|
+          return method if method["name"] == @api_action.to_s
+        end
+        raise "No method documentation found for #{@api_resource}##{@api_action}"
+      end
+
+      def resource_defined?
+        not (@api_resource.nil? or @api_action.nil?)
+      end
+
+    end
+
+  end
+end

data/lib/hammer_cli/apipie/write_command.rb

@@ -0,0 +1,35 @@
+require 'hammer_cli/messages'
+
+module HammerCLI::Apipie
+
+  class WriteCommand < Command
+
+    include HammerCLI::Messages
+
+    def execute
+      send_request
+      print_message
+      return HammerCLI::EX_OK
+    end
+
+    protected
+
+    def print_message
+      msg = success_message
+      output.print_message msg unless msg.nil?
+    end
+
+    def send_request
+      raise "resource or action not defined" unless self.class.resource_defined?
+      resource.send(action, request_params)[0]
+    end
+
+    def request_params
+      method_options
+    end
+
+  end
+
+end
+
+

data/lib/hammer_cli/apipie.rb

@@ -0,0 +1,3 @@
+require File.join(File.dirname(__FILE__), './apipie/command')
+require File.join(File.dirname(__FILE__), './apipie/read_command')
+require File.join(File.dirname(__FILE__), './apipie/write_command')

data/lib/hammer_cli/autocompletion.rb

@@ -0,0 +1,46 @@
+module HammerCLI
+  module Autocompletion
+
+    def autocomplete(line, prefix=[])
+      endings = []
+      formated_prefix = prefix.join(' ')
+
+      if line.length == 0 # look for possible next words
+        all_options = collect_all_options
+        endings = all_options.keys.map { |e| [e, formated_prefix] }
+      elsif line.length == 1 && !(find_subcommand(line[0]) || find_option(line[0])) # look for endings
+        all_options = collect_all_options
+        endings = all_options.select { |k,v| k if k.start_with? line[0] }.keys.map { |e| [e, formated_prefix] }
+      else # dive into subcommands
+        subcommand = find_subcommand line[0]
+        if subcommand
+          command = line.shift
+          prefix << command
+          endings = subcommand.subcommand_class.autocomplete(line, prefix)
+        end
+      end
+      endings
+    end
+
+    def collect_all_options
+      all_options = {}
+
+      if has_subcommands?
+        recognised_subcommands.each do |item|
+          
+          label, _ = item.help
+          all_options[label] = item
+        end
+      end
+
+      recognised_options.each do |item|
+        label, _ = item.help
+        label.split(',').each do |option|
+          all_options[option.split[0]] = item
+        end
+      end
+
+      all_options
+    end
+  end
+end