puppet 5.3.4 → 6.29.0

data/lib/puppet/face/epp.rb

@@ -63,7 +63,7 @@ Puppet::Face.define(:epp, '0.0.1') do
     when_invoked do |*args|
       options = args.pop
       # pass a dummy node, as facts are not needed for validation
-      options[:node] = node = Puppet::Node.new("testnode", :facts => Puppet::Node::Facts.new("facts", {}))
+      options[:node] = Puppet::Node.new("testnode", :facts => Puppet::Node::Facts.new("facts", {}))
       compiler = create_compiler(options)
 
       status = true # no validation error yet
@@ -104,13 +104,19 @@ Puppet::Face.define(:epp, '0.0.1') do
 
   action (:dump) do
     summary _("Outputs a dump of the internal template parse tree for debugging")
-    arguments "-e <source> | [<templates> ...] "
+    arguments "[--format <old|pn|json>] [--pretty] { -e <source> | [<templates> ...] } "
     returns _("A dump of the resulting AST model unless there are syntax or validation errors.")
     description <<-'EOT'
       The dump action parses and validates the EPP syntax and dumps the resulting AST model
       in a human readable (but not necessarily an easy to understand) format.
-      The output format of the dumped tree is intended for epp parser debugging purposes
-      and is not API, and may thus change between versions without deprecation warnings.
+
+      The output format can be controlled using the --format <old|pn|json> where:
+      * 'old' is the default, but now deprecated format which is not API.
+      * 'pn' is the Puppet Extended S-Expression Notation.
+      * 'json' outputs the same graph as 'pn' but with JSON syntax.
+
+      The output will be "pretty printed" when the option --pretty is given together with --format 'pn' or 'json'. 
+      This option has no effect on the 'old' format.
 
       The command accepts one or more templates (.epp) files, or an -e followed by the template
       source text. The given templates can be paths to template files, or references
@@ -137,6 +143,14 @@ Puppet::Face.define(:epp, '0.0.1') do
       summary _("Whether or not to validate the parsed result, if no-validate only syntax errors are reported.")
     end
 
+    option('--format ' + _('<old, pn, or json>')) do
+      summary _("Get result in 'old' (deprecated format), 'pn' (new format), or 'json' (new format in JSON).")
+    end
+
+    option('--pretty') do
+      summary _('Pretty print output. Only applicable together with --format pn or json')
+    end
+
     option("--[no-]header") do
       summary _("Whether or not to show a file name header between files.")
     end
@@ -145,7 +159,7 @@ Puppet::Face.define(:epp, '0.0.1') do
       require 'puppet/pops'
       options = args.pop
       # pass a dummy node, as facts are not needed for dump
-      options[:node] = node = Puppet::Node.new("testnode", :facts => Puppet::Node::Facts.new("facts", {}))
+      options[:node] = Puppet::Node.new("testnode", :facts => Puppet::Node::Facts.new("facts", {}))
       options[:header] = options[:header].nil? ? true : options[:header]
       options[:validate] = options[:validate].nil? ? true : options[:validate]
 
@@ -176,7 +190,7 @@ Puppet::Face.define(:epp, '0.0.1') do
         end
 
         show_filename = templates.count > 1
-        dumps = templates.each do |file|
+        templates.each do |file|
           buffer.print dump_parse(Puppet::FileSystem.read(file, :encoding => 'utf-8'), file, options, show_filename)
         end
 
@@ -353,7 +367,6 @@ Puppet::Face.define(:epp, '0.0.1') do
 
   def dump_parse(source, filename, options, show_filename = true)
     output = ""
-    dumper = Puppet::Pops::Model::ModelTreeDumper.new
     evaluating_parser = Puppet::Pops::Parser::EvaluatingParser::EvaluatingEppParser.new
     begin
       if options[:validate]
@@ -365,7 +378,19 @@ Puppet::Face.define(:epp, '0.0.1') do
       if show_filename && options[:header]
         output << "--- #{filename}\n"
       end
-      output << dumper.dump(parse_result) << "\n"
+      fmt = options[:format]
+      if fmt.nil? || fmt == 'old'
+        output << Puppet::Pops::Model::ModelTreeDumper.new.dump(parse_result) << "\n"
+      else
+        require 'puppet/pops/pn'
+        pn = Puppet::Pops::Model::PNTransformer.transform(parse_result)
+        case fmt
+        when 'json'
+          options[:pretty] ? JSON.pretty_unparse(pn.to_data) : JSON.dump(pn.to_data)
+        else
+          pn.format(options[:pretty] ? Puppet::Pops::PN::Indent.new('  ') : nil, output)
+        end
+      end
     rescue Puppet::ParseError => detail
       if show_filename
         Puppet.err("--- #{filename}")
@@ -377,10 +402,11 @@ Puppet::Face.define(:epp, '0.0.1') do
 
   def get_values(compiler, options)
     template_values = nil
-    if values_file = options[:values_file]
+    values_file = options[:values_file]
+    if values_file
       begin
         if values_file =~ /\.yaml$/
-          template_values = YAML.load_file(values_file)
+          template_values = Puppet::Util::Yaml.safe_load_file(values_file, [Symbol])
         elsif values_file =~ /\.pp$/
           evaluating_parser = Puppet::Pops::Parser::EvaluatingParser.new
           template_values = evaluating_parser.evaluate_file(compiler.topscope, values_file)
@@ -395,7 +421,8 @@ Puppet::Face.define(:epp, '0.0.1') do
       end
     end
 
-    if values = options[:values]
+    values = options[:values]
+    if values
       evaluating_parser = Puppet::Pops::Parser::EvaluatingParser.new
       result = evaluating_parser.evaluate_string(compiler.topscope, values, 'values-hash')
       case result
@@ -413,7 +440,12 @@ Puppet::Face.define(:epp, '0.0.1') do
 
   def render_inline(epp_source, compiler, options)
     template_args = get_values(compiler, options)
-    Puppet::Pops::Evaluator::EppEvaluator.inline_epp(compiler.topscope, epp_source, template_args)
+    result = Puppet::Pops::Evaluator::EppEvaluator.inline_epp(compiler.topscope, epp_source, template_args)
+    if result.instance_of?(Puppet::Pops::Types::PSensitiveType::Sensitive)
+      result.unwrap
+    else
+      result
+    end
   end
 
   def render_file(epp_template_name, compiler, options, show_filename, file_nbr)
@@ -430,7 +462,12 @@ Puppet::Face.define(:epp, '0.0.1') do
       if template_file.nil? && Puppet::FileSystem.exist?(epp_template_name)
         epp_template_name = File.expand_path(epp_template_name)
       end
-      output << Puppet::Pops::Evaluator::EppEvaluator.epp(compiler.topscope, epp_template_name, compiler.environment, template_args)
+      result = Puppet::Pops::Evaluator::EppEvaluator.epp(compiler.topscope, epp_template_name, compiler.environment, template_args)
+      if result.instance_of?(Puppet::Pops::Types::PSensitiveType::Sensitive)
+        output << result.unwrap
+      else
+        output << result
+      end
     rescue Puppet::ParseError => detail
       Puppet.err("--- #{epp_template_name}") if show_filename
       raise detail
@@ -484,9 +521,9 @@ Puppet::Face.define(:epp, '0.0.1') do
       if fact_file.is_a?(Hash) # when used via the Face API
         given_facts = fact_file
       elsif fact_file.end_with?("json")
-        given_facts = JSON.parse(Puppet::FileSystem.read(fact_file, :encoding => 'utf-8'))
+        given_facts = Puppet::Util::Json.load(Puppet::FileSystem.read(fact_file, :encoding => 'utf-8'))
       else
-        given_facts = YAML.load(Puppet::FileSystem.read(fact_file, :encoding => 'utf-8'))
+        given_facts = Puppet::Util::Yaml.safe_load_file(fact_file)
       end
 
       unless given_facts.instance_of?(Hash)

data/lib/puppet/face/facts.rb

@@ -1,5 +1,21 @@
 require 'puppet/indirector/face'
 require 'puppet/node/facts'
+require 'puppet/util/fact_dif'
+
+EXCLUDE_LIST = %w[ ^facterversion$
+  ^load_averages\..*$
+  ^processors\.speed$
+  ^swapfree$ ^swapfree_mb$
+  ^memoryfree$ ^memoryfree_mb$
+  ^memory\.swap\.available_bytes$ ^memory\.swap\.used_bytes$
+  ^memory\.swap\.available$ ^memory\.swap\.capacity$ ^memory\.swap\.used$
+  ^memory\.system\.available_bytes$ ^memory\.system\.used_bytes$
+  ^memory\.system\.available$ ^memory\.system\.capacity$ ^memory\.system\.used$
+  ^mountpoints\..*\.available.*$ ^mountpoints\..*\.capacity$ ^mountpoints\..*\.used.*$
+  ^sp_uptime$ ^system_profiler\.uptime$
+  ^uptime$ ^uptime_days$ ^uptime_hours$ ^uptime_seconds$
+  ^system_uptime\.uptime$ ^system_uptime\.days$ ^system_uptime\.hours$ ^system_uptime\.seconds$
+]
 
 Puppet::Indirector::Face.define(:facts, '0.0.1') do
   copyright "Puppet Inc.", 2011
@@ -35,4 +51,198 @@ Puppet::Indirector::Face.define(:facts, '0.0.1') do
 
   deactivate_action(:destroy)
   deactivate_action(:search)
+
+  action(:upload) do
+    summary _("Upload local facts to the puppet master.")
+    description <<-'EOT'
+      Reads facts from the local system using the `facter` terminus, then
+      saves the returned facts using the rest terminus.
+    EOT
+    returns "Nothing."
+    notes <<-'EOT'
+      This action requires that the puppet master's `auth.conf` file
+      allow `PUT` or `save` access to the `/puppet/v3/facts` API endpoint.
+
+      For details on configuring Puppet Server's `auth.conf`, see:
+
+      <https://puppet.com/docs/puppetserver/latest/config_file_auth.html>
+
+      For legacy Rack-based Puppet Masters, see:
+
+      <https://puppet.com/docs/puppet/latest/config_file_auth.html>
+    EOT
+    examples <<-'EOT'
+      Upload facts:
+
+      $ puppet facts upload
+    EOT
+
+    render_as :json
+
+    when_invoked do |options|
+      # Use `agent` sections  settings for certificates, Puppet Server URL,
+      # etc. instead of `user` section settings.
+      Puppet.settings.preferred_run_mode = :agent
+      Puppet::Node::Facts.indirection.terminus_class = :facter
+
+      facts = Puppet::Node::Facts.indirection.find(Puppet[:node_name_value])
+      unless Puppet[:node_name_fact].empty?
+        Puppet[:node_name_value] = facts.values[Puppet[:node_name_fact]]
+        facts.name = Puppet[:node_name_value]
+      end
+
+      client = Puppet.runtime[:http]
+      session = client.create_session
+      puppet = session.route_to(:puppet)
+
+      Puppet.notice(_("Uploading facts for '%{node}' to '%{server}'") % {
+                    node: Puppet[:node_name_value],
+                    server: puppet.url.hostname})
+
+      puppet.put_facts(Puppet[:node_name_value], facts: facts, environment: Puppet.lookup(:current_environment).name.to_s)
+      nil
+    end
+  end
+
+  action(:diff) do
+    summary _("Compare Facter 3 output with Facter 4 output")
+    description <<-'EOT'
+    Compares output from facter 3 with Facter 4 and prints the differences
+    EOT
+    returns "Differences between Facter 3 and Facter 4 output as an array."
+    notes <<-'EOT'
+    EOT
+    examples <<-'EOT'
+    get differences between facter versions:
+    $ puppet facts diff
+    EOT
+
+    option("--structured") do
+      default_to { false }
+      summary _("Render the different facts as structured.")
+    end
+
+    option("--exclude " + _("<regex>")) do
+      summary _("Regex used to exclude specific facts from diff.")
+    end
+
+    when_invoked do |*args|
+      options = args.pop
+
+      Puppet.settings.preferred_run_mode = :agent
+      Puppet::Node::Facts.indirection.terminus_class = :facter
+
+      if Puppet::Util::Package.versioncmp(Puppet.runtime[:facter].value('facterversion'), '4.0.0') < 0
+        cmd_flags = '--render-as json --show-legacy'
+
+        # puppet/ruby are in PATH since it was updated in the wrapper script
+        puppet_show_cmd  = "puppet facts show"
+        if Puppet::Util::Platform.windows?
+          puppet_show_cmd = "ruby -S -- #{puppet_show_cmd}"
+        end
+
+        facter_3_result = Puppet::Util::Execution.execute("#{puppet_show_cmd} --no-facterng #{cmd_flags}", combine: false)
+        facter_ng_result = Puppet::Util::Execution.execute("#{puppet_show_cmd} --facterng #{cmd_flags}", combine: false)
+
+        exclude_list = options[:exclude].nil? ? EXCLUDE_LIST : EXCLUDE_LIST + [ options[:exclude] ]
+        fact_diff = FactDif.new(facter_3_result, facter_ng_result, exclude_list, options[:structured])
+        fact_diff.difs
+      else
+        Puppet.warning _("Already using Facter 4. To use `puppet facts diff` remove facterng from the .conf file or run `puppet config set facterng false`.")
+        exit 0
+      end
+    end
+
+    when_rendering :console do |result|
+      case result
+      when Array, Hash
+        Puppet::Util::Json.dump(result, :pretty => true)
+      else
+        result
+      end
+    end
+  end
+
+  action(:show) do
+    summary _("Retrieve current node's facts.")
+    arguments _("[<facts>]")
+    description <<-'EOT'
+    Reads facts from the local system using `facter` terminus.
+    A query can be provided to retrieve just a specific fact or a set of facts.
+    EOT
+    returns "The output of facter with added puppet specific facts."
+    notes <<-'EOT'
+
+    EOT
+    examples <<-'EOT'
+    retrieve facts:
+
+    $ puppet facts show os
+    EOT
+
+    option("--config-file " + _("<path>")) do
+      default_to { nil }
+      summary _("The location of the config file for Facter.")
+    end
+
+    option("--custom-dir " + _("<path>")) do
+      default_to { nil }
+      summary _("The path to a directory that contains custom facts.")
+    end
+
+    option("--external-dir " + _("<path>")) do
+      default_to { nil }
+      summary _("The path to a directory that contains external facts.")
+    end
+
+    option("--no-block") do
+      summary _("Disable fact blocking mechanism.")
+    end
+
+    option("--no-cache") do
+      summary _("Disable fact caching mechanism.")
+    end
+
+    option("--show-legacy") do
+      summary _("Show legacy facts when querying all facts.")
+    end
+
+    option("--value-only") do
+      summary _("Show only the value when the action is called with a single query")
+    end
+
+    when_invoked do |*args|
+      options = args.pop
+
+      Puppet.settings.preferred_run_mode = :agent
+      Puppet::Node::Facts.indirection.terminus_class = :facter
+
+      if options[:value_only] && !args.count.eql?(1)
+        options[:value_only] = nil
+        Puppet.warning("Incorrect use of --value-only argument; it can only be used when querying for a single fact!")
+      end
+
+      options[:user_query] = args
+      options[:resolve_options] = true
+      result = Puppet::Node::Facts.indirection.find(Puppet.settings[:certname], options)
+
+      if options[:value_only]
+        result.values.values.first
+      else
+        result.values
+      end
+    end
+
+    when_rendering :console do |result|
+      # VALID_TYPES = [Integer, Float, TrueClass, FalseClass, NilClass, Symbol, String, Array, Hash].freeze
+      # from https://github.com/puppetlabs/facter/blob/4.0.49/lib/facter/custom_facts/util/normalization.rb#L8
+
+      case result
+      when Array, Hash
+        Puppet::Util::Json.dump(result, :pretty => true)
+      else # one of VALID_TYPES above
+        result
+      end
+    end
+  end
 end

data/lib/puppet/face/generate.rb

@@ -58,6 +58,8 @@ Puppet::Face.define(:generate, '0.1.0') do
       Puppet::FileSystem::mkpath(outputdir)
 
       generator.generate(inputs, outputdir, options[:force])
+
+      exit(1) if generator.bad_input?
       nil
     end
   end

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

@@ -1,4 +1,7 @@
 <%# encoding: UTF-8%>
+<% if action.deprecated? -%>
+  <%= "Warning: 'puppet #{action.face.name} #{action.name}' is deprecated and will be removed in a future release." %>
+<% end %>
 <% if action.synopsis -%>
 USAGE: <%= action.synopsis %>
 
@@ -51,6 +54,7 @@ undocumented option
 	end
 	unless action.options.empty?
       action.options.sort.each do |name|
+        next if name == :extra
         option = action.get_option name -%>
 <%= "  " + option.optparse.join(" | ")[0,(optionroom - 1)].ljust(optionroom) + ' - ' -%>
 <%     if !(option.summary) -%>
@@ -83,4 +87,4 @@ undocumented option
 TERMINI: <%= face.class.terminus_classes(face.indirection.name).join(", ") %>
 
 <% end -%>
-See 'puppet man <%= face.name %>' or 'man puppet-<%= face.name %>' for full help.
+See 'puppet help <%= face.name %>' or 'man puppet-<%= face.name %>' for full help.

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

@@ -49,6 +49,7 @@ undocumented option
 	end
  	unless face.options.empty?
       face.options.sort.each do |name|
+        next if name == :extra
         option = face.get_option name -%>
 <%= "  " + option.optparse.join(" | ")[0,(optionroom - 1)].ljust(optionroom) + ' - ' -%>
 <%     if !(option.summary) -%>
@@ -111,4 +112,4 @@ end -%>
 TERMINI: <%= face.class.terminus_classes(face.indirection.name).join(", ") %>
 
 <% end -%>
-See 'puppet man <%= face.name %>' or 'man puppet-<%= face.name %>' for full help.
+See 'puppet help <%= face.name %>' or 'man puppet-<%= face.name %>' for full help.

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

@@ -7,8 +7,8 @@ Available subcommands:
         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 %>
+<% all_application_summaries.each do |appname, summary, indent| -%>
+  <%= indent %><%= appname.to_s.ljust(16) %>  <%= summary %>
 <% end -%>
 
 See 'puppet help <subcommand> <action>' for help on a specific subcommand action.

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

@@ -23,7 +23,7 @@ settings, so you can specify `--server <servername>`, or
 `--run_mode <runmode>` as an argument.
 
 See the configuration file documentation at
-<https://docs.puppetlabs.com/puppet/latest/reference/configuration.html> for the
+<https://puppet.com/docs/puppet/latest/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`.

data/lib/puppet/face/help.rb

@@ -24,57 +24,77 @@ Puppet::Face.define(:help, '0.0.1') do
       summary _("The version of the subcommand for which to show help.")
     end
 
+    option "--ronn" do
+      summary _("Whether to render the help text in ronn format.")
+      default_to { false }
+    end
+
     default
     when_invoked do |*args|
-      # Check our invocation, because we want varargs and can't do defaults
-      # yet.  REVISIT: when we do option defaults, and positional options, we
-      # should rewrite this to use those. --daniel 2011-04-04
       options = args.pop
-      if options.nil? or args.length > 2 then
-        if args.select { |x| x == 'help' }.length > 2 then
-          c = "\n %'(),-./=ADEFHILORSTUXY\\_`gnv|".split('')
-          i = <<-'EOT'.gsub(/\s*/, '').to_i(36)
-            3he6737w1aghshs6nwrivl8mz5mu9nywg9tbtlt081uv6fq5kvxse1td3tj1wvccmte806nb
-            cy6de2ogw0fqjymbfwi6a304vd56vlq71atwmqsvz3gpu0hj42200otlycweufh0hylu79t3
-            gmrijm6pgn26ic575qkexyuoncbujv0vcscgzh5us2swklsp5cqnuanlrbnget7rt3956kam
-            j8adhdrzqqt9bor0cv2fqgkloref0ygk3dekiwfj1zxrt13moyhn217yy6w4shwyywik7w0l
-            xtuevmh0m7xp6eoswin70khm5nrggkui6z8vdjnrgdqeojq40fya5qexk97g4d8qgw0hvokr
-            pli1biaz503grqf2ycy0ppkhz1hwhl6ifbpet7xd6jjepq4oe0ofl575lxdzjeg25217zyl4
-            nokn6tj5pq7gcdsjre75rqylydh7iia7s3yrko4f5ud9v8hdtqhu60stcitirvfj6zphppmx
-            7wfm7i9641d00bhs44n6vh6qvx39pg3urifgr6ihx3e0j1ychzypunyou7iplevitkyg6gbg
-            wm08oy1rvogcjakkqc1f7y1awdfvlb4ego8wrtgu9vzw4vmj59utwifn2ejcs569dh1oaavi
-            sc581n7jjg1dugzdu094fdobtx6rsvk3sfctvqnr36xctold
-          EOT
-          353.times{i,x=i.divmod(1184);a,b=x.divmod(37);print(c[a]*b)}
+
+      unless options[:ronn]
+        if default_case?(args) || help_for_help?(args)
+          return erb('global.erb').result(binding)
         end
-        raise ArgumentError, _("Puppet help only takes two (optional) arguments: a subcommand and an action")
+      end
+
+      if args.length > 2
+        #TRANSLATORS 'puppet help' is a command line and should not be translated
+        raise ArgumentError, _("The 'puppet help' command takes two (optional) arguments: a subcommand and an action")
       end
 
       version = :current
-      if options.has_key? :version then
-        if options[:version].to_s !~ /^current$/i then
+      if options.has_key? :version
+        if options[:version].to_s !~ /^current$/i
           version = options[:version]
         else
-          if args.length == 0 then
-            raise ArgumentError, _("Version only makes sense when a Faces subcommand is given")
+          if args.length == 0
+            #TRANSLATORS '--version' is a command line option and should not be translated
+            raise ArgumentError, _("Supplying a '--version' only makes sense when a Faces subcommand is given")
           end
         end
       end
 
-      return erb('global.erb').result(binding) if args.empty?
-
       facename, actionname = args
-      if legacy_applications.include? facename then
-        if actionname then
-          raise ArgumentError, _("Legacy subcommands don't take actions")
+      if legacy_applications.include? facename
+        if actionname
+          raise ArgumentError, _("The legacy subcommand '%{sub_command}' does not support supplying an action") % { sub_command: facename }
         end
+        # legacy apps already emit ronn output
         return render_application_help(facename)
       else
-        return render_face_help(facename, actionname, version)
+        if options[:ronn]
+          # Calling `puppet help <app> --ronn` normally calls this action with
+          # <app> as the first argument in the `args` array. However, if <app>
+          # happens to match the name of an action, like `puppet help help
+          # --ronn`, then face_base "eats" the argument and `args` will be
+          # empty. Rather than force users to type `puppet help help help
+          # --ronn`, default the facename to `:help`
+          render_face_man(facename || :help)
+        else
+          render_face_help(facename, actionname, version)
+        end
       end
     end
   end
 
+  def default_case?(args)
+    args.empty?
+  end
+
+  def help_for_help?(args)
+    args.length == 1 && args.first == 'help'
+  end
+
+  def render_face_man(facename)
+    # set 'face' as it's used in the erb processing.
+    face = Puppet::Face[facename.to_sym, :current]
+    # avoid unused variable warning
+    _face = face
+    erb('man.erb').result(binding)
+  end
+
   def render_application_help(applicationname)
     return Puppet::Application[applicationname].help
   rescue StandardError, LoadError => detail
@@ -102,7 +122,7 @@ Puppet::Face.define(:help, '0.0.1') do
     face = Puppet::Face[facename.to_sym, version]
     if actionname
       action = face.get_action(actionname.to_sym)
-      if not action
+      if ! action
         fail ArgumentError, _("Unable to load action %{actionname} from %{face}") % { actionname: actionname, face: face }
       end
     end
@@ -138,17 +158,21 @@ Puppet::Face.define(:help, '0.0.1') do
   #  element in the outer array is a pair whose first element is a String containing the application
   #  name, and whose second element is a String containing the summary for that application.
   def all_application_summaries()
-    Puppet::Application.available_application_names.sort.inject([]) do |result, appname|
+    available_application_names_special_sort().inject([]) do |result, appname|
       next result if exclude_from_docs?(appname)
 
-      if (is_face_app?(appname))
+      if (appname == COMMON || appname == SPECIALIZED || appname == BLANK)
+        result << appname
+      elsif (is_face_app?(appname))
         begin
           face = Puppet::Face[appname, :current]
           # Add deprecation message to summary if the face is deprecated
-          summary = face.deprecated? ? face.summary + _(" (Deprecated)") : face.summary
-          result << [appname, summary]
+          summary = face.deprecated? ? face.summary + ' ' + _("(Deprecated)") : face.summary
+          result << [appname, summary, '  ']
         rescue StandardError, LoadError
-          result << [ "! #{appname}", _("! Subcommand unavailable due to error. Check error logs.") ]
+          error_message = _("!%{sub_command}! Subcommand unavailable due to error.") % { sub_command: appname }
+          error_message += ' ' + _("Check error logs.")
+          result << [ error_message, '', '  ' ]
         end
       else
         begin
@@ -156,22 +180,37 @@ Puppet::Face.define(:help, '0.0.1') do
           if summary.empty?
             summary = horribly_extract_summary_from(appname)
           end
-          result << [appname, summary]
+          result << [appname, summary, '  ']
         rescue StandardError, LoadError
-          result << ["! #{appname}", _("! Subcommand unavailable due to error. Check error logs.")]
+          error_message = _("!%{sub_command}! Subcommand unavailable due to error.") % { sub_command: appname }
+          error_message += ' ' + _("Check error logs.")
+          result << [ error_message, '', '  ' ]
         end
       end
     end
   end
 
+  COMMON = 'Common:'.freeze
+  SPECIALIZED = 'Specialized:'.freeze
+  BLANK = "\n".freeze
+  def available_application_names_special_sort()
+    full_list = Puppet::Application.available_application_names
+    a_list = full_list & %w{apply agent config help lookup module resource}
+    a_list = a_list.sort
+    also_ran = full_list - a_list
+    also_ran = also_ran.sort
+    [[COMMON], a_list, [BLANK], [SPECIALIZED], also_ran].flatten(1)
+  end
+
   def horribly_extract_summary_from(appname)
     help = Puppet::Application[appname].help.split("\n")
     # Now we find the line with our summary, extract it, and return it.  This
     # depends on the implementation coincidence of how our pages are
     # formatted.  If we can't match the pattern we expect we return the empty
     # string to ensure we don't blow up in the summary. --daniel 2011-04-11
-    while line = help.shift do
-      if md = /^puppet-#{appname}\([^\)]+\) -- (.*)$/.match(line) then
+    while line = help.shift do #rubocop:disable Lint/AssignmentInCondition
+      md = /^puppet-#{appname}\([^\)]+\) -- (.*)$/.match(line)
+      if md
         return md[1]
       end
     end
@@ -183,7 +222,7 @@ Puppet::Face.define(:help, '0.0.1') do
   #private :horribly_extract_summary_from
 
   def exclude_from_docs?(appname)
-    %w{face_base indirection_base}.include? appname
+    %w{face_base indirection_base cert key man report status}.include? appname
   end
   # This should absolutely be a private method, but for some reason it appears
   #  that you can't use the 'private' keyword inside of a Face definition.

data/lib/puppet/face/key.rb

@@ -8,7 +8,7 @@ Puppet::Indirector::Face.define(:key, '0.0.1') do
   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
+    with 'puppet ssl submit_request'; it should not be necessary to use this
     subcommand directly.
   EOT