puppet-debugger 0.4.0 → 0.4.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: e827c2ef8f176fac5a49ad37ca3aa17ce143595a
-  data.tar.gz: bf1db7841f1b6f1e42e49e84819d02482345cb92
+  metadata.gz: 5495b2df7d84d06cb7871e2201f78c0bfca4240a
+  data.tar.gz: b98315db3c5862050e0afc147868fb48e6306875
 SHA512:
-  metadata.gz: 882a35ed85e35402cd10a39379e99168e2d973341910c0ebca62a8896176477c943f0e23e18cd2fd2daadae01ecae2b90ff1ddfaf4c4b10cd8971177603b6b9e
-  data.tar.gz: d43765702b3c5f8e3ce6cd1f58b09bc2c1c6e8da49e26ac20bd80f444edb100d709f0abe21dea0dca64b7818a6e810ff1f8671a80e3228ad94fae126fe8017c6
+  metadata.gz: 516bb93a8fef0e35e9b100f0f73b604c74acc2449984d0370127f242dd66226e1e894c051b39547eb5273ebc62d8cb713850d534a1b12443c45276a179520695
+  data.tar.gz: b2597ecda5402fe9659ab5d3d54b5b0c08e0c96960db30a4fe9453329257352c3813ef4cc25440e5749873f7798b7d8c4b97965fbeb871b83340b6aa6f5509a1

data/CHANGELOG.md

@@ -1,3 +1,6 @@
+## 0.4.1
+  * Adds a puppet application face
+  * Fixes #41 - add file reference when showing code during code break
 ## 0.4.0
   * Rename to puppet-debugger
 ## 0.3.4

data/DEVELOPMENT.md

@@ -0,0 +1,8 @@
+## Testing
+
+In order to test you need to export the following environment variable when in the project directory.
+The puppet command will then load the face so you can use with `puppet debugger`
+
+`export RUBYLIB=lib/`
+
+`puppet debugger`

data/README.md

@@ -61,7 +61,7 @@ There is a web version of the [puppet-debugger](https://www.puppet-debugger.com)
 limited at this time. In the future we will be adding lots of awesome features to the web repl.
 
 ## Usage
-puppet-debugger will only parse and evaulate your code.  It will not build a catalog
+puppet-debugger will only parse and evaluate your code.  It will not build a catalog
 and try to enforce the catalog. This has a few side affects.
 
 1. Type and provider code will not get run.
@@ -87,6 +87,8 @@ Type "exit", "functions", "vars", "krt", "facts", "reset", "help" for more infor
 
 ```
 
+You can also use the debugger from the puppet command via `puppet debugger`
+
 ## Using Variables
 
 ```

data/lib/puppet/application/debugger.rb

@@ -0,0 +1,306 @@
+require 'puppet/application'
+require 'optparse'
+require 'puppet/util/command_line'
+
+class Puppet::Application::Debugger < Puppet::Application
+  attr_reader :use_facterdb, :use_stdin
+
+  option("--execute EXECUTE","-e") do |arg|
+    options[:code] = arg
+  end
+
+  option("--facterdb-filter FILTER") do |arg|
+    @use_facterdb = true unless options[:node_name]
+    ENV['DEBUGGER_FACTERDB_FILTER'] = arg if arg
+  end
+
+  option("--test") do |_arg|
+    options[:quiet] = true
+    options[:run_once] = true
+    @use_stdin = true
+  end
+
+  option("--no-facterdb") { |_arg| @use_facterdb = false }
+
+  option("--log-level LEVEL","-l") do |arg|
+    Puppet::Util::Log.level = arg.to_sym
+  end
+
+  option("--quiet", "-q") { |_arg| options[:quiet] = true }
+
+  option("--play URL", "-p") do |arg|
+    options[:play] = arg
+  end
+
+  option("--stdin", "-s") { |_arg| @use_stdin = true }
+
+  option("--run-once", '-r') { |_arg| options[:run_once] = true }
+
+  option("--node-name CERTNAME", '-n') do |arg|
+    @use_facterdb = false
+    options[:node_name] = arg
+  end
+
+  def help
+    <<-HELP
+
+puppet-debugger(8) -- Starts a debugger session using the puppet-debugger tool
+========
+
+SYNOPSIS
+--------
+A interactive command line tool for evaluating the puppet language and debugging
+puppet code.
+
+USAGE
+-----
+puppet debugger [--help] [--version] [-e|--execute CODE] [--facterdb-filter FILTER]
+                [--test] [--no-facterdb] [-q|--quiet] [-p|--play URL] [-s|--stdin]
+                [-r|--run-once] [-n|--node-name CERTNAME]
+
+
+DESCRIPTION
+-----------
+A interactive command line tool for evaluating the puppet language and debugging
+puppet code.
+
+USAGE WITH DEBUG MODULE
+-----------------------
+Use the puppet debugger in conjunction with the debug::break() puppet function
+to pry into your code during compilation.  Get immediate insight in how the puppet4
+languge works during the execution of your code.
+
+To use the break function install the module via: puppet module install nwops/debug
+
+Now place the debug::break() function anywhere in your code to
+
+Example:
+  puppet debugger -e '$abs_vars = [-11,-22,-33].map | Integer $num | { debug::break() ; notice($num) }'
+
+See: https://github.com/nwops/puppet-debug
+OPTIONS
+-------
+Note that any setting that's valid in the configuration
+file is also a valid long argument. For example, 'server' is a valid
+setting, so you can specify '--server <servername>' as
+an argument.
+
+See the configuration file documentation at
+http://docs.puppetlabs.com/references/stable/configuration.html for the
+full list of acceptable parameters. A commented list of all
+configuration options can also be generated by running puppet debugger with
+'--genconfig'.
+
+* --help:
+  Print this help message
+
+* --version:
+  Print the puppet version number and exit.
+
+* --execute:
+  Execute a specific piece of Puppet code
+
+* --facterdb-filter
+  Disables the usage of the current node level facts and uses cached facts
+  from facterdb.  Specifying a filter will override the default facterdb filter.
+  Not specifiying a filter will use the default CentOS based filter.
+  This will greatly speed up the start time of the debugger since
+  you are using cached facts.  Additionally, using facterdb also allows you
+  to play with many other operating system facts that you might not have access
+  to.  For example filters please see the facterdb docs.
+
+  See https://github.com/camptocamp/facterdb for more info
+
+* --no-facterdb
+  Use the facts found on this node instead of cached facts from facterdb.
+
+* --log-level
+  Set the Puppet log level which can be very useful with using the debugger.
+
+* --quiet
+  Do not display the debugger help script upon startup.
+
+* --play
+  Plays back the code file supplied into the debugger.  Can also supply
+  any http based url.
+
+* --run-once
+  Return the result from the debugger and exit
+
+* --stdin
+  Read from stdin instead of starting the debugger right away.  Useful when piping code into the debugger.
+
+* --node-name
+  Retrieves the node information remotely via the puppet server given the node name.
+  This is extremely useful when trying to debug classification issues, as this can show
+  classes and parameters retrieved from the ENC.  You can also play around with the real facts
+  of the remote node as well.
+
+  Note: this requires special permission in your puppet server's auth.conf file to allow
+  access to make remote calls from this node: #{Puppet[:certname]}
+
+  You must also have a signed cert and be able to connect to the server from this system.
+
+  Mutually exclusive with --facterdb-filter
+
+* --test
+  Runs the code in the debugger and exit without showing the help screen ( --quiet --run-once, --stdin)
+
+EXAMPLE
+-------
+    $ puppet debugger
+    $ echo "notice('hello, can you hear me?')" | puppet debugger --test
+    $ echo "notice('hello, can you hear me?')" | puppet debugger --stdin
+    $ puppet debugger --execute "notice('hello')"
+    $ puppet debugger --facterdb-filter 'facterversion=/^2.4\./ and operatingsystem=Debian'
+    $ puppet debugger --play https://gist.github.com/logicminds/4f6bcfd723c92aad1f01f6a800319fa4
+    $ puppet debugger --facterdb-filter 'facterversion=/^2.4\./ and operatingsystem=Debian' \\
+                      --play https://gist.github.com/logicminds/4f6bcfd723c92aad1f01f6a800319fa4
+    $ puppet debugger --node-name
+
+
+AUTHOR
+------
+Corey Osman <corey@nwops.io>
+
+
+COPYRIGHT
+---------
+Copyright (c) 2016 NWOps
+
+    HELP
+  end
+
+  def app_defaults
+    Puppet::Settings.app_defaults_for_run_mode(self.class.run_mode).merge(
+        :name => name
+    )
+  end
+
+  def initialize_app_defaults
+    Puppet.settings.initialize_app_defaults(app_defaults)
+  end
+
+  def initialize(command_line = Puppet::Util::CommandLine.new)
+    @command_line = CommandLineArgs.new(command_line.subcommand_name, command_line.args.dup)
+    @options = {}
+    @use_facterdb = true
+    @use_stdin = false
+    begin
+      require 'puppet-debugger'
+      unless ::PuppetDebugger::VERSION >= '0.4.0'
+        Puppet.err('You must install the puppet-debugger gem version >= 0.4.0')
+      end
+    rescue LoadError => e
+      Puppet.err('You must install the puppet-debugger: gem install puppet-debugger')
+    end
+  end
+
+  def main
+    # if this is a file we don't play back since its part of the environment
+    # if just the code we put in a file and use the play feature of the debugger
+    # we could do the same thing with the passed in manifest file but that might be too much code to show
+    manifest = nil
+    if options[:code]
+      code_input = options.delete(:code)
+      file = Tempfile.new(['puppet_repl_input', '.pp'])
+      File.open(file, 'w') do |f|
+        f.write(code_input)
+      end
+      options[:play] = file
+    elsif command_line.args.length == 0 and use_stdin
+      code_input = STDIN.read
+      file = Tempfile.new(['puppet_repl_input', '.pp'])
+      File.open(file, 'w') do |f|
+        f.write(code_input)
+      end
+      options[:play] = file
+    elsif command_line.args.length > 0
+      manifest = command_line.args.shift
+      raise "Could not find file #{manifest}" unless Puppet::FileSystem.exist?(manifest)
+      Puppet.warning("Only one file can be used per run.  Skipping #{command_line.args.join(', ')}") if command_line.args.size > 0
+      options[:play] = file
+    end
+    if ! use_facterdb and options[:node_name].nil?
+      debug_environment = create_environment(nil)
+      Puppet.notice('Gathering node facts...')
+      node = create_node(debug_environment)
+      scope = create_scope(node)
+      # start_debugger(scope)
+      options.merge!({:scope => scope})
+    end
+    ::PuppetDebugger::Cli.start_without_stdin(options)
+  end
+
+  def create_environment(manifest)
+    configured_environment = Puppet.lookup(:current_environment)
+    manifest ?
+        configured_environment.override_with(:manifest => manifest) :
+        configured_environment
+  end
+
+  def create_node(environment)
+    node = nil
+    unless Puppet[:node_name_fact].empty?
+      # Collect our facts.
+      unless facts = Puppet::Node::Facts.indirection.find(Puppet[:node_name_value])
+        raise "Could not find facts for #{Puppet[:node_name_value]}"
+      end
+      Puppet[:node_name_value] = facts.values[Puppet[:node_name_fact]]
+      facts.name = Puppet[:node_name_value]
+    end
+
+    Puppet.override({:current_environment => environment}, "For puppet debugger") do
+      # Find our Node
+      unless node = Puppet::Node.indirection.find(Puppet[:node_name_value])
+        raise "Could not find node #{Puppet[:node_name_value]}"
+      end
+      # Merge in the facts.
+      node.merge(facts.values) if facts
+    end
+    node
+  end
+
+  def create_scope(node)
+    compiler = Puppet::Parser::Compiler.new(node) # creates a new compiler for each scope
+    scope = Puppet::Parser::Scope.new(compiler)
+    # creates a node class
+    scope.source = Puppet::Resource::Type.new(:node, node.name)
+    scope.parent = compiler.topscope
+    # compiling will load all the facts into the scope
+    # without this step facts will not get resolved
+    scope.compiler.compile # this will load everything into the scope
+    scope
+  end
+
+  def start_debugger(scope, options = {})
+    if $stdout.isatty
+      options = options.merge({:scope => scope})
+      # required in order to use convert puppet hash into ruby hash with symbols
+      options = options.inject({}){|data,(k,v)| data[k.to_sym] = v; data}
+      #options[:source_file], options[:source_line] = stacktrace.last
+      ::PuppetRepl::Cli.start(options)
+    else
+      Puppet.info 'puppet debug: refusing to start the debugger without a tty'
+    end
+  end
+
+  # returns a stacktrace of called puppet code
+  # @return [String] - file path to source code
+  # @return [Integer] - line number of called function
+  # This method originally came from the puppet 4.6 codebase and was backported here
+  # for compatibility with older puppet versions
+  # The basics behind this are to find the `.pp` file in the list of loaded code
+  def stacktrace
+    result = caller().reduce([]) do |memo, loc|
+      if loc =~ /\A(.*\.pp)?:([0-9]+):in\s(.*)/
+        # if the file is not found we set to code
+        # and read from Puppet[:code]
+        # $3 is reserved for the stacktrace type
+        memo << [$1.nil? ? :code : $1, $2.to_i]
+      end
+      memo
+    end.reverse
+  end
+
+end

data/lib/puppet-debugger/cli.rb

@@ -204,11 +204,8 @@ Type "exit", "functions", "vars", "krt", "whereami", "facts", "resources", "clas
       repl_obj.remote_node_name = options[:node_name] if options[:node_name]
       repl_obj.initialize_from_scope(options[:scope])
       puts repl_obj.whereami if options[:source_file] and options[:source_line]
-      if options[:play]
-        repl_obj.play_back(options)
-      elsif ! options[:run_once]
-        repl_obj.read_loop
-      end
+      repl_obj.play_back(options) if options[:play]
+      repl_obj.read_loop unless options[:run_once]
     end
 
     # start reads from stdin or from a file

data/lib/puppet-debugger/debugger_code.rb

@@ -22,7 +22,7 @@ require_relative 'code/code_file'
       # @return [Code]
       def from_file(filename, code_type = nil)
         code_file = CodeFile.new(filename, code_type)
-        new(code_file.code, 1, code_file.code_type)
+        new(code_file.code, 1, code_file.code_type, filename)
       end
 
       # Instantiate a `Code` object containing code loaded from a file or
@@ -37,7 +37,7 @@ require_relative 'code/code_file'
     end
 
     # @return [Symbol] The type of code stored in this wrapper.
-    attr_accessor :code_type
+    attr_accessor :code_type, :filename
 
     # Instantiate a `Code` object containing code from the given `Array`,
     # `String`, or `IO`. The first line will be line 1 unless specified
@@ -47,14 +47,15 @@ require_relative 'code/code_file'
     # @param [Array<String>, String, IO] lines
     # @param [Integer?] start_line
     # @param [Symbol?] code_type
-    def initialize(lines = [], start_line = 1, code_type = :ruby)
+    def initialize(lines = [], start_line = 1, code_type = :ruby, filename=nil)
       if lines.is_a? String
         lines = lines.lines
       end
       @lines = lines.each_with_index.map { |line, lineno|
         LOC.new(line, lineno + start_line.to_i) }
       @code_type = code_type
-
+      @filename = filename
+      @with_file_reference = nil
       @with_marker = @with_indentation = nil
     end
 
@@ -181,6 +182,16 @@ require_relative 'code/code_file'
       end
     end
 
+    # Format output with line numbers next to it, unless `y_n` is falsy.
+    #
+    # @param [Boolean?] y_n
+    # @return [Code]
+    def with_file_reference(y_n = true)
+      alter do
+        @with_file_reference = y_n
+      end
+    end
+
     # Format output with a marker next to the given +lineno+, unless +lineno+ is
     # falsy.
     #
@@ -226,9 +237,14 @@ require_relative 'code/code_file'
       print_to_output("", true)
     end
 
+    def add_file_reference
+      "From file: #{File.basename(filename)}\n"
+    end
+
     # Writes a formatted representation (based on the configuration of the
     # object) to the given output, which must respond to `#<<`.
     def print_to_output(output, color=false)
+      output << add_file_reference if @with_file_reference
       @lines.each do |loc|
         loc = loc.dup
         loc.add_line_number(max_lineno_width) if @with_line_numbers

data/lib/puppet-debugger/support/facts.rb

@@ -6,7 +6,7 @@ module PuppetDebugger
 
       # allow the user to specify the facterdb filter
       def dynamic_facterdb_filter
-        ENV['REPL_FACTERDB_FILTER'] || default_facterdb_filter
+        ENV['DEBUGGER_FACTERDB_FILTER'] || default_facterdb_filter
       end
 
       def default_facterdb_filter
@@ -14,7 +14,7 @@ module PuppetDebugger
       end
 
       def facter_version
-        ENV['REPL_FACTER_VERSION'] || default_facter_version
+        ENV['DEBUGGER_FACTER_VERSION'] || default_facter_version
       end
 
       # return the correct supported version of facter facts
@@ -27,11 +27,11 @@ module PuppetDebugger
       end
 
       def facter_os_name
-        ENV['REPL_FACTER_OS_NAME'] || 'Fedora'
+        ENV['DEBUGGER_FACTER_OS_NAME'] || 'Fedora'
       end
 
       def facter_os_version
-        ENV['REPL_FACTER_OS_VERSION'] || '23'
+        ENV['DEBUGGER_FACTER_OS_VERSION'] || '23'
       end
 
       def set_facts(value)

data/lib/puppet-debugger/support/input_responders.rb

@@ -21,7 +21,7 @@ module PuppetDebugger
           else
             code = DebuggerCode.from_file(file, :puppet)
           end
-          return code.with_marker(line_num).around(line_num, 5).with_line_numbers.with_indentation(5).to_s
+          return code.with_marker(line_num).around(line_num, 5).with_line_numbers.with_indentation(5).with_file_reference.to_s
         end
       end
 

data/lib/puppet-debugger/support.rb

@@ -76,7 +76,7 @@ module PuppetDebugger
     end
 
      def keyword_expression
-       @keyword_expression ||= Regexp.new(/^exit|^:set|^play|^classification|^facts|^vars|^functions|^classes|^resources|^krt|^environment|^reset|^help/)
+       @keyword_expression ||= Regexp.new(/^exit|^:set|^play|^classification|^facts|^vars|^functions|^whereami|^classes|^resources|^krt|^environment|^reset|^help/)
      end
 
     def known_resource_types
@@ -142,7 +142,7 @@ module PuppetDebugger
       # in order to call native functions we need to set the global_scope
       ast = generate_ast(input)
       # record the input for puppet to retrieve and reference later
-      file = Tempfile.new(['puppet_repl_input', '.pp'])
+      file = Tempfile.new(['puppet_debugger_input', '.pp'])
       File.open(file, 'w') do |f|
         f.write(input)
       end

data/lib/version.rb

@@ -1,3 +1,3 @@
 module PuppetDebugger
-  VERSION = '0.4.0'
+  VERSION = '0.4.1'
 end

data/spec/facts_spec.rb

@@ -19,7 +19,7 @@ describe 'facts' do
 
   describe '2.4' do
     before(:each) do
-      ENV['REPL_FACTERDB_FILTER'] = nil
+      ENV['DEBUGGER_FACTERDB_FILTER'] = nil
     end
     let(:puppet_version) do
       '4.2.0'
@@ -40,7 +40,7 @@ describe 'facts' do
 
   describe '3.1' do
     before(:each) do
-      ENV['REPL_FACTERDB_FILTER'] = nil
+      ENV['DEBUGGER_FACTERDB_FILTER'] = nil
     end
     let(:puppet_version) do
       '4.5.3'
@@ -65,7 +65,7 @@ describe 'facts' do
   describe 'default facts' do
     describe 'bad filter' do
       before(:each) do
-        ENV['REPL_FACTERDB_FILTER'] = 'facterversion=/^6\.5/'
+        ENV['DEBUGGER_FACTERDB_FILTER'] = 'facterversion=/^6\.5/'
       end
       it 'return filter' do
         expect(debugger.dynamic_facterdb_filter).to eq("facterversion=/^6\\.5/")
@@ -76,7 +76,7 @@ describe 'facts' do
     end
     describe 'good filter' do
       before(:each) do
-        ENV['REPL_FACTERDB_FILTER'] = 'facterversion=/^3\.1/'
+        ENV['DEBUGGER_FACTERDB_FILTER'] = 'facterversion=/^3\.1/'
       end
       it 'return filter' do
         expect(debugger.dynamic_facterdb_filter).to eq("facterversion=/^3\\.1/")

data/spec/puppet/application/debugger_spec.rb

@@ -0,0 +1,67 @@
+#! /usr/bin/env ruby
+require 'spec_helper'
+
+require 'puppet/application/debugger'
+
+describe Puppet::Application::Debugger do
+  let(:debugger) do
+    Puppet::Application[:debugger]
+  end
+
+  let(:environment) do
+    debugger.create_environment(nil)
+  end
+
+  let(:node) do
+    debugger.create_node(environment)
+  end
+
+  let(:scope) do
+    debugger.create_node(node)
+  end
+
+  before :each do
+    debugger.initialize_app_defaults
+  end
+
+  it "declare a main command" do
+    expect(debugger).to respond_to(:main)
+  end
+
+  it 'start the debugger' do
+    expect(PuppetDebugger::Cli).to receive(:start_without_stdin)
+    debugger.run_command
+  end
+
+  it 'start the debugger' do
+    expect(PuppetDebugger::Cli).to receive(:start_without_stdin)
+    debugger.run_command
+  end
+
+  it 'create an environment' do
+    expect(environment).to be_a(Puppet::Node::Environment)
+  end
+
+  it 'shows describtion' do
+    expect(debugger.help).to match(/^puppet-debugger\([^\)]+\) -- (.*)$/)
+  end
+
+  # use --stdin
+  #  use facterdb
+  # not use facterdb
+  # use execute
+  # play
+  # runonce
+  # test
+
+
+  # it 'create a node' do
+  #   require 'pry'; binding.pry
+  #   expect(node).to be_a(Puppet::Node::Environment)
+  # end
+  #
+  # it 'create a scope' do
+  #   expect(scope).to be_a(Puppet::Node::Environment)
+  # end
+
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: puppet-debugger
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.4.1
 platform: ruby
 authors:
 - Corey Osman
@@ -81,6 +81,7 @@ files:
 - ".gitlab-ci.yml"
 - ".rspec"
 - CHANGELOG.md
+- DEVELOPMENT.md
 - Gemfile
 - Gemfile.lock
 - LICENSE.txt
@@ -104,6 +105,7 @@ files:
 - lib/puppet-debugger/support/node.rb
 - lib/puppet-debugger/support/play.rb
 - lib/puppet-debugger/support/scope.rb
+- lib/puppet/application/debugger.rb
 - lib/trollop.rb
 - lib/version.rb
 - puppet-debugger.gemspec
@@ -116,6 +118,7 @@ files:
 - spec/fixtures/sample_start_debugger.pp
 - spec/pdb_spec.rb
 - spec/puppet-debugger_spec.rb
+- spec/puppet/application/debugger_spec.rb
 - spec/remote_node_spec.rb
 - spec/spec_helper.rb
 - spec/support_spec.rb