puppet 4.4.0-universal-darwin

data/lib/puppet/face/help/global.erb

@@ -0,0 +1,16 @@
+<%# encoding: UTF-8%>
+Usage: puppet <subcommand> [options] <action> [options]
+
+Available subcommands:
+    <%# NOTE: this is probably not a good long-term solution for this.  We're only iterating over
+        applications to find the list of things we need to show help for... this works for now
+        because faces can't be run without an application stub.  However, when #6753 is resolved,
+        all of the application stubs for faces will go away, and this will need to be updated
+        to reflect that.  --cprice 2012-04-26 %>
+<% all_application_summaries.each do |appname, summary| -%>
+  <%= appname.to_s.ljust(16) %>  <%= summary %>
+<% end -%>
+
+See 'puppet help <subcommand> <action>' for help on a specific subcommand action.
+See 'puppet help <subcommand>' for help on a specific subcommand.
+Puppet v<%= Puppet.version %>

data/lib/puppet/face/help/man.erb

@@ -0,0 +1,152 @@
+<%# encoding: UTF-8%>
+puppet-<%= face.name %>(8) -- <%= face.summary || "Undocumented subcommand." %>
+<%= '=' * (_erbout.length - 1) %>
+
+<% if face.synopsis -%>
+SYNOPSIS
+--------
+<%= face.synopsis %>
+
+<% end
+   if face.description -%>
+DESCRIPTION
+-----------
+<%= face.description.strip %>
+
+<% end -%>
+OPTIONS
+-------
+Note that any setting that's valid in the configuration
+file is also a valid long argument, although it may or may not be
+relevant to the present action. For example, `server` and `run_mode` are valid
+settings, so you can specify `--server <servername>`, or
+`--run_mode <runmode>` as an argument.
+
+See the configuration file documentation at
+<https://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 with
+`--genconfig`.
+
+* --render-as FORMAT:
+  The format in which to render output. The most common formats are `json`,
+  `s` (string), `yaml`, and `console`, but other options such as `dot` are
+  sometimes available.
+* --verbose:
+  Whether to log verbosely.
+* --debug:
+  Whether to log debug information.
+<% unless face.display_global_options.empty?
+     face.display_global_options.uniq.sort.each do |name|
+		option = name
+		desc = Puppet::Util::Docs.scrub(Puppet.settings.setting(option).desc)
+		type = Puppet.settings.setting(option).default
+		type ||= Puppet.settings.setting(option).type.to_s.upcase -%>
+<%= "* --#{option} #{type}" %>:
+<%= (desc || 'Undocumented setting.').gsub(/^/, '  ') %>
+<%   end
+   end -%>
+<% unless face.options.empty?
+     face.options.sort.each do |name|
+       option = face.get_option name -%>
+<%= "* " + option.optparse.join(" | " ) %>:
+<%= (option.description || option.summary || "Undocumented option.").gsub(/^/, '  ') %>
+<%   end
+   end -%>
+
+ACTIONS
+-------
+<% face.actions.each do |actionname|
+     action = face.get_action(actionname) -%>
+* `<%= action.name.to_s %>` - <%= action.summary %>:
+<%   if action.synopsis -%>
+  `SYNOPSIS`
+
+  <%= action.synopsis %>
+
+<%   end -%>
+  `DESCRIPTION`
+
+<%   if action.description -%>
+<%= action.description.gsub(/^/, '  ') %>
+<% else -%>
+  <%= action.summary || "Undocumented action." %>
+<%   end -%>
+
+<%   unique_options = action.options - face.options
+	 unique_display_global_options = action.display_global_options - face.display_global_options
+     unless unique_options.empty? and unique_display_global_options.empty? -%>
+  `OPTIONS`
+<%      unique_display_global_options.uniq.sort.each do |name|
+		  option = name
+		  desc = Puppet::Util::Docs.scrub(Puppet.settings.setting(option).desc)
+		  type = Puppet.settings.setting(option).default
+		  type ||= Puppet.settings.setting(option).type.to_s.upcase -%>
+  <%= "<--#{option} #{type}>" %> -
+<%= (desc || "Undocumented setting.").gsub(/^/, '  ') %>
+<%      end -%>
+<%     unique_options.sort.each do |name|
+         option = action.get_option name
+         text = (option.description || option.summary || "Undocumented option.").chomp + "\n" -%>
+  <%= '<' + option.optparse.join("> | <") + '>' %> -
+<%= text.gsub(/^/, '  ') %>
+<%     end -%>
+
+<%   end -%>
+<%   if action.returns -%>
+  `RETURNS`
+
+<%= action.returns.gsub(/^/, '  ') %>
+
+<%   end
+     if action.notes -%>
+  `NOTES`
+
+<%= action.notes.gsub(/^/, '  ') %>
+
+<%   end
+   end
+   if face.examples or face.actions.any? {|actionname| face.get_action(actionname).examples} -%>
+EXAMPLES
+--------
+<% end
+   if face.examples -%>
+<%= face.examples %>
+
+<% end
+   face.actions.each do |actionname|
+     action = face.get_action(actionname)
+     if action.examples -%>
+`<%= action.name.to_s %>`
+
+<%= action.examples.strip %>
+
+<%   end
+   end -%>
+
+<% if face.notes or face.respond_to? :indirection -%>
+NOTES
+-----
+<% if face.notes -%>
+<%= face.notes.strip %>
+
+<% end # notes
+if face.respond_to? :indirection -%>
+This subcommand is an indirector face, which exposes `find`, `search`, `save`,
+and `destroy` actions for an indirected subsystem of Puppet. Valid termini for
+this face include:
+
+* `<%= face.class.terminus_classes(face.indirection.name).join("`\n* `") %>`
+
+<% end # indirection
+   end # notes or indirection
+   unless face.authors.empty? -%>
+AUTHOR
+------
+<%= face.authors.join("\n").gsub(/^/, ' * ') %>
+
+<% end -%>
+COPYRIGHT AND LICENSE
+---------------------
+<%= face.copyright %>
+<%= face.license %>

data/lib/puppet/face/key.rb

@@ -0,0 +1,15 @@
+require 'puppet/indirector/face'
+
+Puppet::Indirector::Face.define(:key, '0.0.1') do
+  copyright "Puppet Labs", 2011
+  license   "Apache 2 license; see COPYING"
+
+  summary "Create, save, and remove certificate keys."
+  description <<-'EOT'
+    This subcommand manages certificate private keys. Keys are created
+    automatically by puppet agent and when certificate requests are generated
+    with 'puppet certificate generate'; it should not be necessary to use this
+    subcommand directly.
+  EOT
+
+end

data/lib/puppet/face/man.rb

@@ -0,0 +1,99 @@
+require 'puppet/face'
+require 'puppet/util'
+require 'pathname'
+require 'erb'
+
+Puppet::Face.define(:man, '0.0.1') do
+  copyright "Puppet Labs", 2011
+  license   "Apache 2 license; see COPYING"
+
+  summary "Display Puppet manual pages."
+
+  description <<-EOT
+    This subcommand displays manual pages for all Puppet subcommands. If the
+    `ronn` gem (<https://github.com/rtomayko/ronn/>) is installed on your
+    system, puppet man will display fully-formated man pages. If `ronn` is not
+    available, puppet man will display the raw (but human-readable) source text
+    in a pager.
+  EOT
+
+  notes <<-EOT
+    The pager used for display will be the first found of `$MANPAGER`, `$PAGER`,
+    `less`, `most`, or `more`.
+  EOT
+
+  action(:man) do
+    summary "Display the manual page for a Puppet subcommand."
+    arguments "<subcommand>"
+    returns <<-'EOT'
+      The man data, in Markdown format, suitable for consumption by Ronn.
+
+      RENDERING ISSUES: To skip fancy formatting and output the raw Markdown
+      text (e.g. for use in a pipeline), call this action with '--render-as s'.
+    EOT
+    examples <<-'EOT'
+      View the manual page for a subcommand:
+
+      $ puppet man facts
+    EOT
+
+    default
+    when_invoked do |name, options|
+      if legacy_applications.include? name then
+        return Puppet::Application[name].help
+      end
+
+      face = Puppet::Face[name.to_sym, :current]
+
+      file = (Pathname(__FILE__).dirname + "help" + 'man.erb')
+      erb = ERB.new(file.read, nil, '-')
+      erb.filename = file.to_s
+
+      # Run the ERB template in our current binding, including all the local
+      # variables we established just above. --daniel 2011-04-11
+      return erb.result(binding)
+    end
+
+
+    when_rendering :console do |text|
+      # OK, if we have Ronn on the path we can delegate to it and override the
+      # normal output process.  Otherwise delegate to a pager on the raw text,
+      # otherwise we finally just delegate to our parent.  Oh, well.
+
+      # These are the same options for less that git normally uses.
+      # -R : Pass through color control codes (allows display of colors)
+      # -X : Don't init/deinit terminal (leave display on screen on exit)
+      # -F : automatically exit if display fits entirely on one screen
+      # -S : don't wrap long lines
+      ENV['LESS'] ||= 'FRSX'
+
+      ronn  = Puppet::Util.which('ronn')
+      pager = [ENV['MANPAGER'], ENV['PAGER'], 'less', 'most', 'more'].
+        detect {|x| x and x.length > 0 and Puppet::Util.which(x) }
+
+      if ronn then
+        # ronn is a stupid about pager selection, we can be smarter. :)
+        if pager then ENV['PAGER'] = pager end
+
+        args  = "--man --manual='Puppet Manual' --organization='Puppet Labs, LLC'"
+        IO.popen("#{ronn} #{args}", 'w') do |fh| fh.write text end
+
+        ''                      # suppress local output, neh?
+      elsif pager then
+        IO.popen(pager, 'w') do |fh| fh.write text end
+        ''
+      else
+        text
+      end
+    end
+  end
+
+  def legacy_applications
+    # The list of applications, less those that are duplicated as a face.
+    Puppet::Application.available_application_names.reject do |appname|
+      Puppet::Face.face? appname.to_sym, :current or
+        # ...this is a nasty way to exclude non-applications. :(
+        %w{face_base indirection_base}.include? appname
+    end
+  end
+end

data/lib/puppet/face/module.rb

@@ -0,0 +1,19 @@
+require 'puppet/face'
+require 'puppet/module_tool'
+require 'puppet/util/colors'
+
+Puppet::Face.define(:module, '1.0.0') do
+  extend Puppet::Util::Colors
+
+  copyright "Puppet Labs", 2012
+  license   "Apache 2 license; see COPYING"
+
+  summary "Creates, installs and searches for modules on the Puppet Forge."
+  description <<-EOT
+    This subcommand can find, install, and manage modules from the Puppet Forge,
+    a repository of user-contributed Puppet code. It can also generate empty
+    modules, and prepare locally developed modules for release on the Forge.
+  EOT
+
+  display_global_options "environment", "modulepath"
+end

data/lib/puppet/face/module/build.rb

@@ -0,0 +1,63 @@
+Puppet::Face.define(:module, '1.0.0') do
+  action(:build) do
+    summary "Build a module release package."
+    description <<-EOT
+      Prepares a local module for release on the Puppet Forge by building a
+      ready-to-upload archive file.
+
+      This action uses the metadata.json file in the module directory to set metadata
+      used by the Forge. See <https://docs.puppetlabs.com/puppet/latest/reference/modules_publishing.html> for more
+      about writing metadata.json files.
+
+      After being built, the release archive file can be found in the module's
+      `pkg` directory.
+    EOT
+
+    returns "Pathname object representing the path to the release archive."
+
+    examples <<-EOT
+      Build a module release:
+
+      $ puppet module build puppetlabs-apache
+      notice: Building /Users/kelseyhightower/puppetlabs-apache for release
+      Module built: /Users/kelseyhightower/puppetlabs-apache/pkg/puppetlabs-apache-0.0.1.tar.gz
+
+      Build the module in the current working directory:
+
+      $ cd /Users/kelseyhightower/puppetlabs-apache
+      $ puppet module build
+      notice: Building /Users/kelseyhightower/puppetlabs-apache for release
+      Module built: /Users/kelseyhightower/puppetlabs-apache/pkg/puppetlabs-apache-0.0.1.tar.gz
+    EOT
+
+    arguments "[<path>]"
+
+    when_invoked do |*args|
+      options = args.pop
+      if options.nil? or args.length > 1 then
+        raise ArgumentError, "puppet module build only accepts 0 or 1 arguments"
+      end
+
+      module_path = args.first
+      if module_path.nil?
+        pwd = Dir.pwd
+        module_path = Puppet::ModuleTool.find_module_root(pwd)
+        if module_path.nil?
+          raise "Unable to find metadata.json in module root #{pwd} or parent directories. See <https://docs.puppetlabs.com/puppet/latest/reference/modules_publishing.html> for required file format."
+        end
+      else
+        unless Puppet::ModuleTool.is_module_root?(module_path)
+          raise "Unable to find metadata.json in module root #{module_path} or parent directories. See <https://docs.puppetlabs.com/puppet/latest/reference/modules_publishing.html> for required file format."
+        end
+      end
+
+      Puppet::ModuleTool.set_option_defaults options
+      Puppet::ModuleTool::Applications::Builder.run(module_path, options)
+    end
+
+    when_rendering :console do |return_value|
+      # Get the string representation of the Pathname object.
+      "Module built: " + return_value.expand_path.to_s
+    end
+  end
+end

data/lib/puppet/face/module/changes.rb

@@ -0,0 +1,42 @@
+Puppet::Face.define(:module, '1.0.0') do
+  action(:changes) do
+    summary "Show modified files of an installed module."
+    description <<-EOT
+      Shows any files in a module that have been modified since it was
+      installed. This action compares the files on disk to the md5 checksums
+      included in the module's checksums.json or, if that is missing, in
+      metadata.json.
+    EOT
+
+    returns "Array of strings representing paths of modified files."
+
+    examples <<-EOT
+      Show modified files of an installed module:
+
+      $ puppet module changes /etc/puppetlabs/code/modules/vcsrepo/
+      warning: 1 files modified
+      lib/puppet/provider/vcsrepo.rb
+    EOT
+
+    arguments "<path>"
+
+    when_invoked do |path, options|
+      Puppet::ModuleTool.set_option_defaults options
+      unless root_path = Puppet::ModuleTool.find_module_root(path)
+        raise ArgumentError, "Could not find a valid module at #{path.inspect}"
+      end
+      Puppet::ModuleTool::Applications::Checksummer.run(root_path, options)
+    end
+
+    when_rendering :console do |return_value|
+      if return_value.empty?
+        Puppet.notice "No modified files"
+      else
+        Puppet.warning "#{return_value.size} files modified"
+      end
+      return_value.map do |changed_file|
+        "#{changed_file}"
+      end.join("\n")
+    end
+  end
+end

data/lib/puppet/face/module/generate.rb

@@ -0,0 +1,251 @@
+Puppet::Face.define(:module, '1.0.0') do
+  action(:generate) do
+    summary "Generate boilerplate for a new module."
+    description <<-EOT
+      Generates boilerplate for a new module by creating the directory
+      structure and files recommended for the Puppet community's best practices.
+
+      A module may need additional directories beyond this boilerplate
+      if it provides plugins, files, or templates.
+    EOT
+
+    returns "Array of Pathname objects representing paths of generated files."
+
+    examples <<-EOT
+      Generate a new module in the current directory:
+
+      $ puppet module generate puppetlabs-ssh
+      We need to create a metadata.json file for this module.  Please answer the
+      following questions; if the question is not applicable to this module, feel free
+      to leave it blank.
+
+      Puppet uses Semantic Versioning (semver.org) to version modules.
+      What version is this module?  [0.1.0]
+      -->
+
+      Who wrote this module?  [puppetlabs]
+      -->
+
+      What license does this module code fall under?  [Apache-2.0]
+      -->
+
+      How would you describe this module in a single sentence?
+      -->
+
+      Where is this module's source code repository?
+      -->
+
+      Where can others go to learn more about this module?
+      -->
+
+      Where can others go to file issues about this module?
+      -->
+
+      ----------------------------------------
+      {
+        "name": "puppetlabs-ssh",
+        "version": "0.1.0",
+        "author": "puppetlabs",
+        "summary": null,
+        "license": "Apache-2.0",
+        "source": "",
+        "project_page": null,
+        "issues_url": null,
+        "dependencies": [
+          {
+            "name": "puppetlabs-stdlib",
+            "version_requirement": ">= 1.0.0"
+          }
+        ]
+      }
+      ----------------------------------------
+
+      About to generate this metadata; continue? [n/Y]
+      -->
+
+      Notice: Generating module at /Users/username/Projects/puppet/puppetlabs-ssh...
+      Notice: Populating ERB templates...
+      Finished; module generated in puppetlabs-ssh.
+      puppetlabs-ssh/manifests
+      puppetlabs-ssh/manifests/init.pp
+      puppetlabs-ssh/metadata.json
+      puppetlabs-ssh/README.md
+      puppetlabs-ssh/spec
+      puppetlabs-ssh/spec/spec_helper.rb
+      puppetlabs-ssh/tests
+      puppetlabs-ssh/tests/init.pp
+    EOT
+
+    option "--skip-interview" do
+      summary "Bypass the interactive metadata interview"
+      description <<-EOT
+        Do not attempt to perform a metadata interview.  Primarily useful for automatic
+        execution of `puppet module generate`.
+      EOT
+    end
+
+    arguments "<name>"
+
+    when_invoked do |name, options|
+      # Since we only want to interview if it's being rendered to the console
+      # (i.e. when invoked with `puppet module generate`), we can't do any work
+      # here in the when_invoked block. The result of this block is then
+      # passed to each renderer, which will handle it appropriately; by
+      # returning a simple message like this, every renderer will simply output
+      # the string.
+      # Our `when_rendering :console` handler will ignore this value and
+      # actually generate the module.
+      #
+      # All this is necessary because it is not possible at this point in time
+      # to know what the destination of the output is.
+      "This format is not supported by this action."
+    end
+
+    when_rendering :console do |_, name, options|
+      Puppet::ModuleTool.set_option_defaults options
+
+      begin
+        # A default dependency for all newly generated modules is being
+        # introduced as a substitute for the comments we used to include in the
+        # previous module data specifications. While introducing a default
+        # dependency is less than perfectly desirable, the cost is low, and the
+        # syntax is obtuse enough to justify its inclusion.
+        metadata = Puppet::ModuleTool::Metadata.new.update(
+          'name' => name,
+          'version' => '0.1.0',
+          'dependencies' => [
+            { 'name' => 'puppetlabs-stdlib', 'version_requirement' => '>= 1.0.0' }
+          ]
+        )
+      rescue ArgumentError
+        msg = "Could not generate directory #{name.inspect}, you must specify a dash-separated username and module name."
+        raise ArgumentError, msg, $!.backtrace
+      end
+
+      dest = Puppet::ModuleTool::Generate.destination(metadata)
+      result = Puppet::ModuleTool::Generate.generate(metadata, options[:skip_interview])
+
+      path = dest.relative_path_from(Pathname.pwd)
+      puts "Finished; module generated in #{path}."
+      result.join("\n")
+    end
+  end
+end
+
+module Puppet::ModuleTool::Generate
+  module_function
+
+  def generate(metadata, skip_interview = false)
+    interview(metadata) unless skip_interview
+    destination = duplicate_skeleton(metadata)
+    all_files = destination.basename + '**/*'
+
+    return Dir[all_files.to_s]
+  end
+
+  def interview(metadata)
+    puts "We need to create a metadata.json file for this module.  Please answer the"
+    puts "following questions; if the question is not applicable to this module, feel free"
+    puts "to leave it blank."
+
+    begin
+      puts
+      puts "Puppet uses Semantic Versioning (semver.org) to version modules."
+      puts "What version is this module?  [#{metadata.version}]"
+      metadata.update 'version' => user_input(metadata.version)
+    rescue
+      Puppet.err "We're sorry, we could not parse that as a Semantic Version."
+      retry
+    end
+
+    puts
+    puts "Who wrote this module?  [#{metadata.author}]"
+    metadata.update 'author' => user_input(metadata.author)
+
+    puts
+    puts "What license does this module code fall under?  [#{metadata.license}]"
+    metadata.update 'license' => user_input(metadata.license)
+
+    puts
+    puts "How would you describe this module in a single sentence?"
+    metadata.update 'summary' => user_input(metadata.summary)
+
+    puts
+    puts "Where is this module's source code repository?"
+    metadata.update 'source' => user_input(metadata.source)
+
+    puts
+    puts "Where can others go to learn more about this module?#{ metadata.project_page && "  [#{metadata.project_page}]" }"
+    metadata.update 'project_page' => user_input(metadata.project_page)
+
+    puts
+    puts "Where can others go to file issues about this module?#{ metadata.issues_url && "  [#{metadata.issues_url}]" }"
+    metadata.update 'issues_url' => user_input(metadata.issues_url)
+
+    puts
+    puts '-' * 40
+    puts metadata.to_json
+    puts '-' * 40
+    puts
+    puts "About to generate this metadata; continue? [n/Y]"
+
+    if user_input('Y') !~ /^y(es)?$/i
+      puts "Aborting..."
+      exit 0
+    end
+  end
+
+  def user_input(default=nil)
+    print '--> '
+    input = STDIN.gets.chomp.strip
+    input = default if input == ''
+    return input
+  end
+
+  def destination(metadata)
+    return @dest if defined? @dest
+    @dest = Pathname.pwd + metadata.name
+    raise ArgumentError, "#{@dest} already exists." if @dest.exist?
+    return @dest
+  end
+
+  def duplicate_skeleton(metadata)
+    dest = destination(metadata)
+
+    puts
+    Puppet.notice "Generating module at #{dest}..."
+    FileUtils.cp_r skeleton_path, dest
+
+    populate_templates(metadata, dest)
+    return dest
+  end
+
+  def populate_templates(metadata, destination)
+    Puppet.notice "Populating templates..."
+
+    formatters = {
+      :erb      => proc { |data, ctx| ERB.new(data).result(ctx) },
+      :template => proc { |data, _| data },
+    }
+
+    formatters.each do |type, block|
+      templates = destination + "**/*.#{type}"
+
+      Dir.glob(templates.to_s, File::FNM_DOTMATCH).each do |erb|
+        path = Pathname.new(erb)
+        content = block[path.read, binding]
+
+        target = path.parent + path.basename(".#{type}")
+        target.open('w') { |f| f.write(content) }
+        path.unlink
+      end
+    end
+  end
+
+  def skeleton_path
+    return @path if defined? @path
+    path = Pathname(Puppet.settings[:module_skeleton_dir])
+    path = Pathname(__FILE__).dirname + '../../module_tool/skeleton/templates/generator' unless path.directory?
+    @path = path
+  end
+end