hammer_cli 0.0.4 → 0.0.5

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: cec260aec7ea81ebce48b8efe53cd738f8e63266
+  data.tar.gz: 1aa5bb89e0dc87783b4bd093a2b8dffb58ac9616
+SHA512:
+  metadata.gz: 0ea5172e0d0b8d3fdb743a3f26d3cf1a5ad351360b607f1a4343b7a09303b8d77c9c417106027a5163f49ac4382a158f31cdf23501d47d230594e44d92fa3e47
+  data.tar.gz: 6637eb0f497677b719636ac5b91c12e5ac3da1b96b68e95b49f36831a0d69ed7e355ada97dbd79d4b0ff9b08b4765f725a25fe8e9e934238522b3de7065729cf

data/README.md

@@ -1,27 +1,83 @@
-Hammer - the CLI tool for foreman
+Hammer - the CLI tool for Foreman
 =================================
 
-![Design draft](doc/design.png)
+Hammer is a generic [clamp-based](https://github.com/mdub/clamp) CLI framework. Hammer-cli is just a core without any commands.
 
-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 core can be extended with plugins and customized according to your application setup. Any Ruby script can be easily turned into a command so possibilities are wide.
 
+Currently available plugins are:
+  - [hammer-cli-foreman](https://github.com/theforeman/hammer-cli-foreman)  - commands corresponding to Foreman API
+  - [hammer-cli-katello-bridge](https://github.com/theforeman/hammer-cli-katello-bridge) - set of commands provided by Katello CLI
 
-The CLI has
+You also can easily add custom commands specific for your use, such as various bulk actions or admin tasks.
 
- - 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)
 
+Installation instructions
+-------------------------
 
-How to run
-----------
+Hammer CLI is packaged for the following RPM based distributions:
 
-The work is in progress and there are still no builds ready, but instaling from sources is easy. You will need rake, bundler.
+ - RHEL and derivatives, version 6
+ - Fedora 18, 19
+
+
+#### Step 1: setup rpm repositories
+Add the Foreman's nightly rpm repository to your yum repo files. For Fedora installations replace 'el6' with 'f18' or 'f19' as appropriate.
+
+```bash
+http://yum.theforeman.org/nightly/el6/$basearch/
+```
+
+On RHEL systems you will also have to add [EPEL repository](https://fedoraproject.org/wiki/EPEL) as it contains some of the required dependencies.
+
+
+#### Step 2: install hammer core
+```
+$ yum install rubygem-hammer_cli
+```
+
+
+#### Step 3: install plugins
+Currently, there are two plugins, both available as rpm packages.
+
+ - commands for managing foreman
+```
+$ yum install rubygem-hammer_cli_foreman
+```
+
+ - 1:1 bridge to [katello cli](https://github.com/Katello/katello)
+```
+$ yum install rubygem-hammer_cli_katello_bridge
+```
+
+Plugins are disabled after the installation. You have to edit the config file and enable them manually.
+
+
+#### Step 4: configuration
+
+Edit ```/etc/foreman/cli_config.yml``` or ```~/.foreman/cli_config.yml``` and uncomment lines with names of modules you've just installed to enable them:
+
+```yaml
+:modules:
+# - hammer_cli_foreman
+# - hammer_cli_katello_bridge
+```
+
+Confirm your setup by running ```$ hammer -h``` and see if the desired commands are listed.
+
+You will also most likely want to change the url of the Foreman server.
+
+```yaml
+:host: 'https://localhost/'
+:username: 'admin'
+:password: 'changeme'
+```
+
+Done. Your hammer client is configured and ready to use.
+
+#### Git installation
+Optionally you can install hammer from git checkouts. You will need ```rake``` and ```bundler```.
 Clone and install CLI core
 
     $ git clone git@github.com:theforeman/hammer-cli.git
@@ -36,47 +92,22 @@ clone plugin with foreman commands
     $ 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
+
+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. 
+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/
 

data/bin/hammer

@@ -2,6 +2,8 @@
 
 require 'rubygems'
 require 'clamp'
+require 'highline'
+HighLine.color_scheme = HighLine::SampleColorScheme.new
 
 # create fake command instance to use some global args before we start
 class PreParser < Clamp::Command

data/lib/hammer_cli/abstract.rb

@@ -6,6 +6,8 @@ require 'logging'
 
 module HammerCLI
 
+  class CommandConflict < StandardError; end
+
   class AbstractCommand < Clamp::Command
 
     extend Autocompletion
@@ -14,7 +16,7 @@ module HammerCLI
     end
 
     def run(arguments)
-      exit_code = super(arguments)
+      exit_code = super
       raise "exit code must be integer" unless exit_code.is_a? Integer
       return exit_code
     rescue => e
@@ -24,7 +26,7 @@ module HammerCLI
     end
 
     def parse(arguments)
-      super(arguments)
+      super
       validate_options
       logger.info "Called with options: %s" % options.inspect
     rescue HammerCLI::Validator::ValidationError => e
@@ -35,7 +37,7 @@ module HammerCLI
       HammerCLI::EX_OK
     end
 
-    def self.validate_options &block
+    def self.validate_options(&block)
       self.validation_block = block
     end
 
@@ -43,18 +45,47 @@ module HammerCLI
       validator.run &self.class.validation_block if self.class.validation_block
     end
 
-
     def output
-      @output ||= HammerCLI::Output::Output.new
+      @output ||= HammerCLI::Output::Output.new(:context => context)
     end
 
     def exception_handler
       @exception_handler ||= exception_handler_class.new :output => output
     end
 
+    def initialize(*args)
+      super
+      context[:path] ||= []
+      context[:path] << self
+    end
+
+    def parent_command
+      context[:path][-2]
+    end
+
+    def self.subcommand!(name, description, subcommand_class = self, &block)
+      self.recognised_subcommands.delete_if do |sc|
+        if sc.is_called?(name)
+          Logging.logger[self].info "subcommand #{name} (#{sc.subcommand_class}) replaced with #{name} (#{subcommand_class})"
+          true
+        else
+          false
+        end
+      end
+      self.subcommand(name, description, subcommand_class, &block)
+    end
+
+    def self.subcommand(name, description, subcommand_class = self, &block)
+      existing = find_subcommand(name)
+      if existing
+        raise HammerCLI::CommandConflict, "can't replace subcommand #{name} (#{existing.subcommand_class}) with #{name} (#{subcommand_class})"
+      end
+      super
+    end
+
     protected
 
-    def logger name=self.class
+    def logger(name=self.class)
       logger = Logging.logger[name]
       logger.extend(HammerCLI::Logger::Watch) if not logger.respond_to? :watch
       logger
@@ -65,7 +96,7 @@ module HammerCLI
       @validator ||= HammerCLI::Validator.new(options)
     end
 
-    def handle_exception e
+    def handle_exception(e)
       exception_handler.handle_exception(e)
     end
 
@@ -80,6 +111,23 @@ module HammerCLI
       return HammerCLI::ExceptionHandler
     end
 
+    def self.desc(desc=nil)
+      @desc = desc if desc
+      @desc
+    end
+
+    def self.command_name(name=nil)
+      @name = name if name
+      @name
+    end
+
+    def self.autoload_subcommands
+      commands = constants.map { |c| const_get(c) }.select { |c| c <= HammerCLI::AbstractCommand }
+      commands.each do |cls|
+        subcommand cls.command_name, cls.desc, cls
+      end
+    end
+
     def all_options
       self.class.recognised_options.inject({}) do |h, opt|
         h[opt.attribute_name] = send(opt.read_method)

data/lib/hammer_cli/apipie/command.rb

@@ -19,7 +19,7 @@ module HammerCLI::Apipie
       self.class.identifier_option(:label, "resource label")
     end
 
-    def self.identifiers *keys
+    def self.identifiers(*keys)
       @identifiers ||= {}
       keys.each do |key|
         if key.is_a? Hash
@@ -35,6 +35,12 @@ module HammerCLI::Apipie
       validator.any(*self.class.declared_identifiers.values).required
     end
 
+    def self.desc(desc=nil)
+      super(desc) || resource.docs_for(action)["apis"][0]["short_description"]
+    rescue
+      " "
+    end
+
     protected
 
     def get_identifier
@@ -45,7 +51,7 @@ module HammerCLI::Apipie
       [nil, nil]
     end
 
-    def self.identifier? key
+    def self.identifier?(key)
       if @identifiers
         return true if @identifiers.keys.include? key
       else

data/lib/hammer_cli/apipie/options.rb

@@ -8,14 +8,14 @@ module HammerCLI::Apipie
     end
 
     def all_method_options
-      method_options_for_params(self.class.method_doc["params"], true)
+      method_options_for_params(resource.docs_for(action)["params"], true)
     end
 
     def method_options
-      method_options_for_params(self.class.method_doc["params"], false)
+      method_options_for_params(resource.docs_for(action)["params"], false)
     end
 
-    def method_options_for_params params, include_nil=true
+    def method_options_for_params(params, include_nil=true)
       opts = {}
       params.each do |p|
         if p["expected_type"] == "hash"
@@ -32,18 +32,18 @@ module HammerCLI::Apipie
 
     module ClassMethods
 
-      def apipie_options options={}
+      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)
+        options_for_params(resource.docs_for(action)["params"], filter)
       end
 
       protected
 
-      def options_for_params params, filter
+      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"
@@ -54,7 +54,7 @@ module HammerCLI::Apipie
         end
       end
 
-      def create_option param
+      def create_option(param)
         option(
           option_switches(param),
           option_type(param),
@@ -64,27 +64,27 @@ module HammerCLI::Apipie
         )
       end
 
-      def option_switches param
+      def option_switches(param)
         '--' + param["name"].gsub('_', '-')
       end
 
-      def option_type param
+      def option_type(param)
         param["name"].upcase.gsub('-', '_')
       end
 
-      def option_desc param
+      def option_desc(param)
         desc = param["description"].gsub(/<\/?[^>]+?>/, "")
         return " " if desc.empty?
         return desc
       end
 
-      def option_opts param
+      def option_opts(param)
         opts = {}
         opts[:required] = true if param["required"]
         return opts
       end
 
-      def option_formatter param
+      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"

data/lib/hammer_cli/apipie/read_command.rb

@@ -4,19 +4,14 @@ module HammerCLI::Apipie
 
   class ReadCommand < Command
 
-      def self.output definition=nil, &block
+      def self.output(definition=nil, &block)
         dsl = HammerCLI::Output::Dsl.new
-        dsl.build &block
+        dsl.build &block if block_given?
 
         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
@@ -40,11 +35,11 @@ module HammerCLI::Apipie
       protected
       def retrieve_data
         raise "resource or action not defined" unless self.class.resource_defined?
-        resource.send(action, request_params)[0]
+        resource.call(action, request_params)[0]
       end
 
       def print_data(records)
-        output.print_records(records, self.class.heading)
+        output.print_records(records)
       end
 
       def request_params

data/lib/hammer_cli/apipie/resource.rb

@@ -1,4 +1,49 @@
 module HammerCLI::Apipie
+
+  class ResourceDefinition
+
+    attr_reader :resource_class
+
+    def initialize(resource_class)
+      @resource_class = resource_class
+    end
+
+    def name
+      resource_class.name.split("::")[-1].downcase
+    end
+
+    def docs_for(method_name)
+      resource_class.doc["methods"].each do |method|
+        return method if method["name"] == method_name.to_s
+      end
+      raise "No method documentation found for #{resource_class}##{action}"
+    end
+
+  end
+
+
+  class ResourceInstance < ResourceDefinition
+
+    def initialize(resource_class, config)
+      super(resource_class)
+      @instance = resource_class.new(config)
+    end
+
+    def self.from_definition(definition, config)
+      self.new(definition.resource_class, config)
+    end
+
+    def call(method_name, params=nil)
+      instance.send(method_name, params)
+    end
+
+    private
+
+    attr_reader :instance
+
+  end
+
+
   module Resource
 
     def self.included(base)
@@ -6,8 +51,13 @@ module HammerCLI::Apipie
     end
 
     def resource
-      @resource ||= self.class.resource.new resource_config
-      @resource
+      # if the resource definition is not available in this command's class
+      # try to look it up in parent command's class
+      if self.class.resource
+        return ResourceInstance.from_definition(self.class.resource, resource_config)
+      else
+        return ResourceInstance.from_definition(self.parent_command.class.resource, resource_config)
+      end
     end
 
     def action
@@ -24,28 +74,28 @@ module HammerCLI::Apipie
 
     module ClassMethods
 
-
-      def resource resource=nil, action=nil
-        @api_resource = resource unless resource.nil?
+      def resource(resource_class=nil, action=nil)
+        @api_resource = ResourceDefinition.new(resource_class) unless resource_class.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
+        # if the resource definition is not available in this class
+        # try to look it up in it's enclosing module/class
+        enclosing_module = self.name.split("::")[0..-2].inject(Object) { |mod, cls| mod.const_get cls }
 
-      def method_doc
-        @api_resource.doc["methods"].each do |method|
-          return method if method["name"] == @api_action.to_s
+        if enclosing_module.respond_to? :resource
+          enclosing_module.resource
         end
-        raise "No method documentation found for #{@api_resource}##{@api_action}"
+      end
+
+      def action(action=nil)
+        @api_action = action unless action.nil?
+        return @api_action if @api_action
+        return superclass.action if superclass.respond_to? :action
       end
 
       def resource_defined?
-        not (@api_resource.nil? or @api_action.nil?)
+        not (resource.nil? or action.nil?)
       end
 
     end

data/lib/hammer_cli/apipie/write_command.rb

@@ -21,7 +21,7 @@ module HammerCLI::Apipie
 
     def send_request
       raise "resource or action not defined" unless self.class.resource_defined?
-      resource.send(action, request_params)[0]
+      resource.call(action, request_params)[0]
     end
 
     def request_params

data/lib/hammer_cli/exception_handler.rb

@@ -4,7 +4,7 @@ require 'logging'
 module HammerCLI
   class ExceptionHandler
 
-    def initialize options={}
+    def initialize(options={})
       @output = options[:output] or raise "Missing option output"
       @logger = Logging.logger['Exception']
     end
@@ -17,7 +17,7 @@ module HammerCLI
       ]
     end
 
-    def handle_exception e, options={}
+    def handle_exception(e, options={})
       @options = options
       handler = mappings.reverse.find { |m| e.class.respond_to?(:"<=") ? e.class <= m[0] : false }
       return send(handler[1], e) if handler
@@ -26,7 +26,7 @@ module HammerCLI
 
     protected
 
-    def print_error error
+    def print_error(error)
       error = error.join("\n") if error.kind_of? Array
       @logger.error error
 
@@ -37,26 +37,26 @@ module HammerCLI
       end
     end
 
-    def log_full_error e
+    def log_full_error(e)
       backtrace = e.backtrace || []
-      @logger.error "\n\n#{e.class} (#{e.message}):\n    " + 
+      @logger.error "\n\n#{e.class} (#{e.message}):\n    " +
         backtrace.join("\n    ")
         "\n\n"
-    end 
+    end
 
-    def handle_general_exception e
+    def handle_general_exception(e)
       print_error "Error: " + e.message
       log_full_error e
       HammerCLI::EX_SOFTWARE
     end
 
-    def handle_not_found e
+    def handle_not_found(e)
       print_error e.message
       log_full_error e
       HammerCLI::EX_NOT_FOUND
     end
 
-    def handle_unauthorized e
+    def handle_unauthorized(e)
       print_error "Invalid username or password"
       log_full_error e
       HammerCLI::EX_UNAUTHORIZED

data/lib/hammer_cli/main.rb

@@ -15,6 +15,8 @@ module HammerCLI
       exit(HammerCLI::EX_OK)
     end
 
+    option ["--show-ids"], :flag, "Show ids of associated resources"
+
     option ["-P", "--ask-pass"], :flag, "Ask for password" do 
       context[:password] = get_password()
       ''
@@ -28,6 +30,10 @@ module HammerCLI
       exit(HammerCLI::EX_OK)
     end
 
+    def show_ids=(show_ids)
+      context[:show_ids] = show_ids
+    end
+
     def password=(password)
       context[:password] = password.nil? ? ENV['FOREMAN_PASSWORD'] : password
     end

data/lib/hammer_cli/messages.rb

@@ -6,7 +6,7 @@ module HammerCLI
       base.extend(ClassMethods)
     end
 
-    def success_message_for action
+    def success_message_for(action)
       self.class.success_message_for action
     end
 
@@ -14,7 +14,7 @@ module HammerCLI
       self.class.success_message
     end
 
-    def failure_message_for action
+    def failure_message_for(action)
       self.class.failure_message_for action
     end
 
@@ -22,28 +22,28 @@ module HammerCLI
       self.class.failure_message
     end
 
-    def handle_exception e
+    def handle_exception(e)
       exception_handler.handle_exception e, :heading => failure_message
     end
 
     module ClassMethods
-      def success_message_for action, msg=nil
+      def success_message_for(action, msg=nil)
         @success_message ||= {}
         @success_message[action] = msg unless msg.nil?
         @success_message[action]
       end
 
-      def success_message msg=nil
+      def success_message(msg=nil)
         success_message_for :default, msg
       end
 
-      def failure_message_for action, msg=nil
+      def failure_message_for(action, msg=nil)
         @failure_message ||= {}
         @failure_message[action] = msg unless msg.nil?
         @failure_message[action]
       end
 
-      def failure_message msg=nil
+      def failure_message(msg=nil)
         failure_message_for :default, msg
       end
     end