puppet-debugger 0.6.1 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 44f5198a38560ebf262df1bb5d9fb27b4689f6d0
-  data.tar.gz: 76718414d5e49a617b755e6157f29b2188ff52cf
+  metadata.gz: 6e41642281d06f230cba649f0ad0cca8845fc713
+  data.tar.gz: 5f51ef9afa5c431937be5fa750978b3bedcf1b70
 SHA512:
-  metadata.gz: 84b776b0a55d4d9cc116d4bf5a9ef8d67ecde7a8b6ac357b9f9af5dd990c555f258de0ea87ba1c5a359733ff8ec6524eac4e60d0a66d4858e8dbb4a0299a2c1c
-  data.tar.gz: d47bae21bef89a828e225bcb9095bb4bd1c7a40af174891ae4c17bd69eb487795deff60718ccac0aa9b1e1e7e48fa433b6ed140386e69418be2b29ce79aa00b0
+  metadata.gz: 991540c9bb5dbd2e8995695818f0c05ce139c2832cfccd793ad01b3c062d242fd70026b4d4b2d19773b0268d0bc6d8d6709241dbe8bf030dd0663215ec43f1bf
+  data.tar.gz: bd44969d0b5b2c934de7f4705ed6fa9828363d9c5e8a4a8bbcd672da351885552ab3e54d2b8197a26b56d6729fab21a97aa7eb536f4c6da0e07c73e1959ee6d5

data/.gitignore

@@ -1,4 +1,5 @@
 # rcov generated
+Gemfile.lock
 .bash_history
 .gems
 .gem

data/.gitlab-ci.yml

@@ -31,7 +31,7 @@ rubocop_ruby:
   only:
     - branches
   tags:
-    - ruby2.2
+    - ruby
   script:
     - bundle install
     - bundle exec rubocop -D
@@ -73,8 +73,13 @@ bump_and_tag:
 .ruby_23: &ruby23
   image: ruby:2.3
 
+.ruby_24: &ruby24
+  image: ruby:2.4
+
 gem_production:
   image: ruby:2.1
+  tags:
+    - ruby
   before_script:
     - gem install dpl
   stage: deploy
@@ -85,72 +90,84 @@ gem_production:
 
 puppet_38_ruby193:
   variables:
-    PUPPET_GEM_VERSION: "~> 3.8"
+    PUPPET_GEM_VERSION: "~> 3.8.0"
   <<: *puppet_job_def
   <<: *ruby193
 
 puppet_38_ruby20:
   variables:
-    PUPPET_GEM_VERSION: "~> 3.8"
+    PUPPET_GEM_VERSION: "~> 3.8.0"
   <<: *puppet_job_def
   <<: *ruby20
 
 puppet_38_ruby21:
   variables:
-    PUPPET_GEM_VERSION: "~> 3.8"
+    PUPPET_GEM_VERSION: "~> 3.8.0"
   <<: *puppet_job_def
   <<: *ruby21
 
 puppet_43_ruby20:
   variables:
-    PUPPET_GEM_VERSION: "~> 4.3"
+    PUPPET_GEM_VERSION: "~> 4.3.0"
   <<: *puppet_job_def
   <<: *ruby20
 
 puppet_43_ruby21:
   variables:
-    PUPPET_GEM_VERSION: "~> 4.3"
+    PUPPET_GEM_VERSION: "~> 4.3.0"
   <<: *puppet_job_def
   <<: *ruby21
 
 puppet_43_ruby22:
   variables:
-    PUPPET_GEM_VERSION: "~> 4.3"
+    PUPPET_GEM_VERSION: "~> 4.3.0"
   <<: *puppet_job_def
   <<: *ruby22
 
 puppet_44_ruby21:
   variables:
-    PUPPET_GEM_VERSION: "~> 4.4"
+    PUPPET_GEM_VERSION: "~> 4.4.0"
   <<: *puppet_job_def
   <<: *ruby21
 
 puppet_44_ruby22:
   variables:
-    PUPPET_GEM_VERSION: "~> 4.4"
+    PUPPET_GEM_VERSION: "~> 4.4.0"
   <<: *puppet_job_def
   <<: *ruby22
 
 puppet_45_ruby21:
   variables:
-    PUPPET_GEM_VERSION: "~> 4.5"
+    PUPPET_GEM_VERSION: "~> 4.5.0"
   <<: *puppet_job_def
   <<: *ruby21
 
 puppet_46_ruby22:
   variables:
-    PUPPET_GEM_VERSION: "~> 4.6"
+    PUPPET_GEM_VERSION: "~> 4.6.0"
   <<: *puppet_job_def
   <<: *ruby22
 
 puppet_47_ruby22:
   variables:
-    PUPPET_GEM_VERSION: "~> 4.7"
+    PUPPET_GEM_VERSION: "~> 4.7.0"
   <<: *puppet_job_def
   <<: *ruby22
 
 puppet_48_ruby22:
   variables:
-    PUPPET_GEM_VERSION: "~> 4.8"
+    PUPPET_GEM_VERSION: "~> 4.8.0"
   <<: *puppet_job_def
   <<: *ruby22
+
+puppet_49_ruby23:
+  variables:
+    PUPPET_GEM_VERSION: "~> 4.9.0"
+  <<: *puppet_job_def
+  <<: *ruby23
+
+puppet_410_ruby24:
+  variables:
+    PUPPET_GEM_VERSION: "~> 4.10.0"
+  <<: *puppet_job_def
+  <<: *ruby24

data/.rubocop.yml

@@ -15,6 +15,7 @@ AllCops:
     - lib/version.rb
     - lib/puppet-debugger.rb
     - bin
+
 # Offense count: 7
 # Configuration parameters: AllowSafeAssignment.
 Lint/AssignmentInCondition:
@@ -30,7 +31,8 @@ Lint/Debugger:
   Exclude:
     - spec/**/*.rb
 
-
+Style/NumericPredicate:
+  Enabled: false
 # Offense count: 1
 # Cop supports --auto-correct.
 # Configuration parameters: AlignWith, SupportedStyles, AutoCorrect.

data/.rubocop_todo.yml

@@ -63,10 +63,18 @@ Lint/UselessAssignment:
 Metrics/AbcSize:
   Max: 150
 
+Style/IndentHeredoc:
+  Enabled: false
+
+Style/FileName:
+  Exclude:
+    - Rakefile
+    - Gemfile
+    - puppet-debugger.gemspec
 # Offense count: 3
 # Configuration parameters: CountComments.
 Metrics/BlockLength:
-  Max: 442
+  Max: 518
 
 # Offense count: 3
 Metrics/BlockNesting:
@@ -89,7 +97,7 @@ Metrics/MethodLength:
 # Offense count: 2
 # Configuration parameters: CountComments.
 Metrics/ModuleLength:
-  Max: 115
+  Max: 168
 
 # Offense count: 10
 Metrics/PerceivedComplexity:
@@ -154,6 +162,7 @@ Style/GuardClause:
     - 'lib/puppet-debugger/support/input_responders.rb'
     - 'lib/puppet-debugger/support/play.rb'
     - 'lib/trollop.rb'
+    - puppet-debugger.gemspec
 
 # Offense count: 2
 Style/IdenticalConditionalBranches:

data/.ruby-version

@@ -1 +1 @@
-2.3.1
+2.3.3

data/CHANGELOG.md

@@ -1,3 +1,12 @@
+## Unreleased
+
+## 0.7.0
+  * Adds new commands command 
+  * Adds new help command 
+  * Adds plugin framework
+  * Adds hooks framework
+  * Moves all commands to plugins
+  * Adds pluginator gem
 ## 0.6.1
   * Adds benchmark feature
 ## 0.6.0

data/DEVELOPMENT.md

@@ -5,4 +5,9 @@ The puppet command will then load the face so you can use with `puppet debugger`
 
 `export RUBYLIB=lib/`
 
-`puppet debugger`
+`puppet debugger`
+
+
+## Plugin Development
+ * [Plugin Development Guide](Plugin_development.md)
+ 

data/Gemfile

@@ -1,21 +1,23 @@
-source "http://rubygems.org"
-gem 'puppet', ENV['PUPPET_GEM_VERSION'] || "~> 4.9.0"
-gem 'facterdb', ">= 0.3.8"
-gem 'awesome_print', "~> 1.6"
-
-group :test do
+# frozen_string_literal: true
+source 'http://rubygems.org'
+gem 'awesome_print', '~> 1.7'
+gem 'facterdb', '~> 0.3.8'
+gem 'puppet', ENV['PUPPET_GEM_VERSION'] || '~> 4.10.1'
+gem 'pluginator', '~> 1.4.1'
+group :test, :development do
   # ruby versions prior to 2.0 cannot install json_pure 2.0.2+
+  gem 'bundler'
+  gem 'CFPropertyList'
   gem 'json_pure', '<= 2.0.1'
-  gem "rdoc", "~> 3.12"
-  gem "rspec"
-  gem "bundler"
-  gem "simplecov", ">= 0"
+  gem 'pry'
+  gem 'puppet-debugger', path: './'
   gem 'rake'
+  gem 'rdoc', '~> 3.12'
   gem 'release_me'
-  gem 'pry'
+  gem 'rspec', '~> 3.6'
+  gem 'simplecov', '>= 0'
 end
 
 group :validate do
   gem 'rubocop'
 end
-

data/Plugin_development.md

@@ -0,0 +1,304 @@
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+**Table of Contents**  *generated with [DocToc](https://github.com/thlorenz/doctoc)*
+
+- [Plugin Development Guide](#plugin-development-guide)
+  - [Creating a new Plugin](#creating-a-new-plugin)
+  - [Creating a plugin as a gem](#creating-a-plugin-as-a-gem)
+    - [Testing your gem plugin code](#testing-your-gem-plugin-code)
+  - [Creating a plugin to be merged into core](#creating-a-plugin-to-be-merged-into-core)
+  - [New Plugin Instructions](#new-plugin-instructions)
+  - [Required Directory layout](#required-directory-layout)
+  - [Run Method](#run-method)
+  - [Required Constants](#required-constants)
+    - [Command words](#command-words)
+    - [Summary](#summary)
+    - [Command groups](#command-groups)
+  - [Plugin API](#plugin-api)
+  - [Debugger Hooks](#debugger-hooks)
+    - [Hook Events](#hook-events)
+  - [Calling other plugins](#calling-other-plugins)
+    - [Indirectly](#indirectly)
+    - [Directly](#directly)
+  - [Testing your plugin code](#testing-your-plugin-code)
+  - [Examples](#examples)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+
+# Plugin Development Guide
+The puppet debugger now features a plugin system.  This was added to support future expansion
+via third party developers.  
+
+At this time there is only a single type of plugin called InputResponder, but in the future there will be additional types of plugins.
+
+## Creating a new Plugin
+There are two ways to package a plugin.
+
+1. create a core plugin to be merged into the puppet-debugger codebase
+2. create a external plugin packaged as a gem and distributed via gem server such as rubygems.org
+
+If you think your plugin should be in the core please create a PR and ensure you have unit test coverage for your plugin.
+
+## Creating a plugin as a gem
+For reference you can use the following doc [How to create a gem](http://bundler.io/v1.15/guides/creating_gem.html)
+
+1. Create the gem via `bundle gem <plugin_name>`
+
+    ```
+    bundle gem --test=rspec fancy_plugin
+    cd fancy_plugin
+    mkdir -p lib/plugins/puppet-debugger/input_responders
+    
+    ```
+    
+2. Add the following to your Gemfile
+    ```ruby
+    group :dev, :test do
+      gem 'puppet-debugger'
+      gem 'pry'
+      gem 'CFPropertyList'
+      gem 'rake'
+      gem 'rspec', '>= 3.6'
+      # loads itself so you don't have to update RUBYLIB path
+      gem 'your_plugin', path: './'
+    end
+    ```
+    
+3. bundle install    
+2. Follow the [New Plugin Instructions](#new-plugin-instructions)
+3. Version the gem
+4. Package and push the gem to rubygems.
+5. Tell others about it.
+
+### Testing your gem plugin code
+In order to test your plugin gem with the puppet-debugger you will need to add your gem's lib path to the RUBYLIB environment variable.
+
+`RUBYLIB=~/path_to_gem/lib:$RUBYLIB puppet debugger`
+
+Once this is set, puppet-debugger will discover your gem automatically and you should see it in the commands list.
+
+Note: if you add the your plugin to the Gemfile as shown above in step 2 there is no need to set the RUBYLIB variable.
+
+## Creating a plugin to be merged into core
+1. Fork the puppet-debugger repo
+1. Follow the [New Plugin Instructions](#new-plugin-instructions)
+2. Submit a PR 
+
+
+## New Plugin Instructions
+1. Create a file with the name of your plugin lib/plugins/puppet-debugger/input_responders/fancy_plugin.rb
+2. Add the following content to the plugin.
+
+    ```
+    require 'puppet-debugger/input_responder_plugin'
+    module PuppetDebugger
+      module InputResponders
+        class Fancy < InputResponderPlugin
+          COMMAND_WORDS = %w(fancy)
+          SUMMARY = 'This is a fancy plugin'
+          COMMAND_GROUP = :tools
+    
+          def run(args = [])
+            'hello from a fancy plugin'
+          end
+        end
+      end
+    end
+    ```
+
+4. ensure the class name is the same as the file name which follows ruby best practices
+5. Add words to the COMMAND_WORDS constant which will be used to run your plugin from the debugger.
+6. Add a short summary that describes your plugin's functionality
+7. Add a group to which your plugin should belong to.  This appears in the `commands` plugin output.
+8. You must implement the [Run Method](#run-method).  This method is called when your plugin's command word is entered.
+9. Write unit tests to validate your code works.
+
+You can review the [Required Constants](#required-constants) docs for more info.
+
+## Required Directory layout
+In order for you plugin to be discovered you must create this exact directly layout.  Your plugin file must be in
+the following directory `lib/plugins/puppet-debugger/input_responders/`
+
+If you are packaging as a gem you must still provide this directory layout in addition to whatever other supporting files
+are also in your gem.
+
+## Run Method
+
+Your plugin must override the run method.  When your plugin is executed, an array is passed as the args variable.
+This variable contains all the arguments that can be supplied to your plugin.  It is not required that you utilize
+the `args` variable as some plugins run without arguments but it must be the only argument.
+
+For example: `fancy hello there sir` would be passed as ['hello', 'there', 'sir'] to your plugin's run method.
+
+
+```ruby
+def run(args = [])
+  greeting = args.first
+  "#{greeting} from a fancy plugin"
+end
+
+```
+
+## Required Constants
+
+### Command words
+These are the words the user will enter to interact with your plugin.  You can provide
+multiple words but only the first word will show up in the commands help screen.
+
+Example:
+
+```
+2:>> classes
+[
+  [0] "settings",
+  [1] "__node_regexp__foo"
+]
+2:>>
+```
+
+Ensure you set the following in your plugin class
+`COMMAND_WORDS = %w(fancy werd)`
+ 
+### Summary
+Set the Summary Constant to tell users what your plugin does.  This will show up in the commands help
+screen.
+
+```bash
+Tools
+   fancy            This is a fancy plugin that does nothing
+```
+
+`SUMMARY = 'This is a fancy plugin that does nothing'`
+    
+
+### Command groups
+The group name appears on the commands help screen and categories tools
+based on the value of the command_group constant ie. `COMMAND_GROUP = :tools`
+
+Below is a list of groups you can use to categorize your plugin.  Groups are created dynamically by simply supplying
+a new group name.
+
+* `:help`
+* `:tools`
+* `:scope`
+* `:node`
+* `:environment`
+* `:editing`
+* `:context`
+ 
+## Plugin API
+Every plugin has access to debugger's central objects.  You may need to use these objects to implement your plugin.
+
+Objects exposed that you might want access to:
+
+* debugger     (direct use is not recommended)
+* scope        (The puppet scope object)        
+* node         (The puppet node object)       
+* environment  (The puppet environment object)
+* facts        (The puppet facts hash)    
+* compiler     (The puppet compiler object)    
+* catalog      (The puppet catalog)
+* function_map (Current map of functions)
+
+While you do have access to the `debugger` object itself and everything inside this object.  I would recommend not using the debugger
+object directly since the debugger code base is changing rapidly.  Usage can result in a broken plugin.  If you are using
+the debugger object directly please open an issue so we can create a interface for your use case to provide future compatibility. 
+
+## Debugger Hooks
+In addition the plugin API you can run code during certain events in the debugger lifecycle.  This allows you to run your plugin code
+only when certain actions occur.  Please remember that your hook's code will be run multiple times during the debugger's session.
+
+If your hook code takes a while to run, please ensure it runs fast or throw the code into a separate thread if applicable.
+
+### Hook Events
+Below is a list of the current events that you can hook into.
+
+ * after_output  (After the debugger has returned control back to the console)
+ * before_eval   (Occurs before puppet evaluates the code)
+ * after_eval    (Occurs after puppet evaluates the code and before the debugger sends the output to the console)
+ 
+To hook into a debugger event you just add a hook via the `add_hook` method with the name of the event you wish to hook into.
+ 
+An example of this pattern is below.  In this example, when `graph` is entered by the user, the plugin toggles the execution
+of creating a graph after the output is sent to the console.  The toggle either adds or deletes the hook.  Since creating the graph
+can take a while we also create a thread so we don't hold the console hostage.  A new graph is created each time a puppet evaluation occurs.
+
+```ruby
+def run(args = [])
+    toggle_status
+end
+
+def toggle_status
+    status = !status
+    if status
+      add_hook(:after_eval, :create_graph) do |code, debugger|
+        # ensure we only start a single thread, otherwise they could stack up
+        # and try to write to the same file.
+        Thread.kill(@graph_thread) if @graph_thread
+        @graph_thread = Thread.new { create_html(create_graph_content) }
+      end
+      out = "Graph mode enabled at #{get_url}"
+    else
+      delete_hook(:after_output, :create_graph_content)
+      out = "Graph mode disabled"
+    end
+    out
+end
+```
+
+## Calling other plugins
+There are two ways to call other plugins.
+
+### Indirectly 
+You can call another plugin via the handle_input method ie. `debugger.handle_input('help')`.  Just use the plugin command word
+and any arguments that it takes to call the plugin.
+
+This makes the debugger handle the loading of the plugin and returns formatted output which is most of the time what you want.
+This does not send any output to the console so it is up to you to decide what to do next.
+
+### Directly
+Should you want to call the plugin directly you can bypass the `handle_input` method and use the `plugin_from_command`
+to return the plugin instance.
+
+```
+# get a plugin instance
+play_plugin = PuppetDebugger::InputResponders::Commands.plugin_from_command('play')
+
+# execute the plugin  
+args = ['https://gists.github.com/sdalfsdfadsfds.txt']
+# pass an instance of the debugger (always do this)
+output = plugin.execute(args, debugger)
+
+```
+
+If the command used to find the plugin is incorrect a `PuppetDebugger::Exception::InvalidCommand` error will be raised.
+
+## Testing your plugin code
+1. Create a new rspec test file as `spec/input_responders/plugin_name_spec.rb`
+
+At a minimum you will need the following test code.  By including the shared examples `plugin_tests' you will automatially
+inherit some basic tests for your plugin.  However, you will need to further test your code by creating additional
+tests.
+
+Replace `:plugin_name ` with the name of your plugin command word.
+
+```ruby
+require 'spec_helper'
+require 'puppet-debugger'
+require 'puppet-debugger/plugin_test_helper'
+
+describe :plugin_name do
+  include_examples "plugin_tests"
+  let(:args) { [] }
+  
+  # you must test your run implementation similar to this, if you have args please set them in the args let blocks
+  it 'works' do
+    expect(plugin.run(args)).to eq('????')
+  end
+end
+  
+```
+
+## Examples
+There are plenty of examples of plugins that are in the core code base.  See lib/plugins/puppet-debugger/input_responders 
+for examples.