Merge branch '2.7.x' into 2.7.next

Conflicts:
 * spec/unit/node/facts_spec.rb

Updates:
 * spec/unit/interface/action{,_builder}_spec.rb
   => update for 'when_invoked' block being required.

25 files changed, 711 insertions, 189 deletions

diff --git a/lib/puppet/face/catalog.rb b/lib/puppet/face/catalog.rb
index 0dcde3591..4624313bc 100644
--- a/lib/puppet/face/catalog.rb
+++ b/lib/puppet/face/catalog.rb
@@ -1,8 +1,56 @@
-require 'puppet/face/indirector'
+require 'puppet/indirector/face'
+
+Puppet::Indirector::Face.define(:catalog, '0.0.1') do
+  copyright "Puppet Labs", 2011
+  license   "Apache 2 license; see COPYING"
+
+  summary "Compile, save, view, and convert catalogs."
+  description <<-EOT
+    This face primarily interacts with the compiling subsystem. By default,
+    it compiles a catalog using the default manifest and the hostname from
+    `certname`, but you can choose to retrieve a catalog from the server by
+    specifying `--terminus rest`.  You can also choose to print any catalog
+    in 'dot' format (for easy graph viewing with OmniGraffle or Graphviz)
+    with '--render-as dot'.
+  EOT
+  notes <<-EOT
+    This is an indirector face, which exposes find, search, save, and
+    destroy actions for an indirected subsystem of Puppet. Valid terminuses
+    for this face include:
+
+    * `active_record`
+    * `compiler`
+    * `queue`
+    * `rest`
+    * `yaml`
+  EOT
 
-Puppet::Face::Indirector.define(:catalog, '0.0.1') do
   action(:apply) do
-    when_invoked do |catalog, options|
+    summary "Apply a Puppet::Resource::Catalog object"
+    description <<-EOT
+      Applies a catalog object retrieved with the `download` action. This
+      action cannot consume a serialized catalog, and is not intended for
+      command-line use."
+    EOT
+    notes <<-EOT
+      This action returns a Puppet::Transaction::Report object.
+    EOT
+    examples <<-EOT
+      From `secret_agent.rb`:
+
+          Puppet::Face[:plugin, '0.0.1'].download
+
+          facts   = Puppet::Face[:facts, '0.0.1'].find(certname)
+          catalog = Puppet::Face[:catalog, '0.0.1'].download(certname, facts)
+          report  = Puppet::Face[:catalog, '0.0.1'].apply(catalog)
+
+          Puppet::Face[:report, '0.0.1'].submit(report)
+    EOT
+
+    when_invoked do |options|
+      catalog = Puppet::Face[:catalog, "0.0.1"].find(Puppet[:certname]) or raise "Could not find catalog for #{Puppet[:certname]}"
+      catalog = catalog.to_ral
+
       report = Puppet::Transaction::Report.new("apply")
       report.configuration_version = catalog.version
 
@@ -23,18 +71,38 @@ Puppet::Face::Indirector.define(:catalog, '0.0.1') do
   end
 
   action(:download) do
-    when_invoked do |certname, facts, options|
+    summary "Download this node's catalog from the puppet master server"
+    description <<-EOT
+      Retrieves a catalog from the puppet master. Unlike the `find` action,
+      `download` submits facts to the master as part of the request. This
+      action is not intended for command-line use.
+    EOT
+    notes "This action returns a Puppet::Resource::Catalog object."
+    examples <<-EOT
+      From `secret_agent.rb`:
+
+          Puppet::Face[:plugin, '0.0.1'].download
+
+          facts   = Puppet::Face[:facts, '0.0.1'].find(certname)
+          catalog = Puppet::Face[:catalog, '0.0.1'].download(certname, facts)
+          report  = Puppet::Face[:catalog, '0.0.1'].apply(catalog)
+
+          Puppet::Face[:report, '0.0.1'].submit(report)
+    EOT
+    when_invoked do |options|
       Puppet::Resource::Catalog.indirection.terminus_class = :rest
-      facts_to_upload = {:facts_format => :b64_zlib_yaml, :facts => CGI.escape(facts.render(:b64_zlib_yaml))}
+      Puppet::Resource::Catalog.indirection.cache_class = nil
       catalog = nil
       retrieval_duration = thinmark do
-        catalog = Puppet::Face[:catalog, '0.0.1'].find(certname, facts_to_upload)
+        catalog = Puppet::Face[:catalog, '0.0.1'].find(Puppet[:certname])
       end
-      catalog = catalog.to_ral
-      catalog.finalize
       catalog.retrieval_duration = retrieval_duration
       catalog.write_class_file
-      catalog
+
+      Puppet::Resource::Catalog.indirection.terminus_class = :yaml
+      Puppet::Face[:catalog, "0.0.1"].save(catalog)
+      Puppet.notice "Saved catalog for #{Puppet[:certname]} to yaml"
+      nil
     end
   end
 end
diff --git a/lib/puppet/face/catalog/select.rb b/lib/puppet/face/catalog/select.rb
index ba27117bc..a6c97a627 100644
--- a/lib/puppet/face/catalog/select.rb
+++ b/lib/puppet/face/catalog/select.rb
@@ -1,10 +1,42 @@
 # Select and show a list of resources of a given type.
 Puppet::Face.define(:catalog, '0.0.1') do
   action :select do
+    summary "Select and show a list of resources of a given type"
+    description <<-EOT
+      Retrieves a catalog for the specified host and returns an array of
+      resources of the given type. This action is not intended for
+      command-line use.
+    EOT
+    notes <<-NOTES
+      The type name for this action must be given in its capitalized form.
+      That is, calling `catalog select mynode file` will return an empty
+      array, whereas calling it with 'File' will return a list of the node's
+      file resources.
+
+      By default, this action will retrieve a catalog from Puppet's compiler
+      subsystem; you must call the action with `--terminus rest` if you wish
+      to retrieve a catalog from the puppet master.
+    NOTES
     when_invoked do |host, type, options|
+      # REVISIT: Eventually, type should have a default value that triggers
+      # the non-specific behaviour.  For now, though, this will do.
+      # --daniel 2011-05-03
       catalog = Puppet::Resource::Catalog.indirection.find(host)
 
-      catalog.resources.reject { |res| res.type != type }.each { |res| puts res }
+      if type == '*'
+        catalog.resources
+      else
+        type = type.downcase
+        catalog.resources.reject { |res| res.type.downcase != type }
+      end
+    end
+
+    when_rendering :console do |value|
+      if value.nil? then
+        "no matching resources found"
+      else
+        value.map {|x| x.to_s }.join("\n")
+      end
     end
   end
 end
diff --git a/lib/puppet/face/certificate.rb b/lib/puppet/face/certificate.rb
index 4c2950fb3..ee2b2873f 100644
--- a/lib/puppet/face/certificate.rb
+++ b/lib/puppet/face/certificate.rb
@@ -1,15 +1,51 @@
-require 'puppet/face/indirector'
+require 'puppet/indirector/face'
 require 'puppet/ssl/host'
 
-Puppet::Face::Indirector.define(:certificate, '0.0.1') do
+Puppet::Indirector::Face.define(:certificate, '0.0.1') do
+  copyright "Puppet Labs", 2011
+  license   "Apache 2 license; see COPYING"
+
+  summary "Provide access to the CA for certificate management"
+  description <<-EOT
+    This face interacts with a local or remote Puppet certificate
+    authority. Currently, its behavior is not a full superset of puppet
+    cert; specifically, it is unable to mimic puppet cert's "clean" option,
+    and its "generate" action submits a CSR rather than creating a
+    signed certificate.
+  EOT
+  notes <<-EOT
+    This is an indirector face, which exposes find, search, save, and
+    destroy actions for an indirected subsystem of Puppet. Valid terminuses
+    for this face include:
+
+    * `ca`
+    * `file`
+    * `rest`
+  EOT
+
   option "--ca-location LOCATION" do
+    summary "The certificate authority to query"
+    description <<-EOT
+      Whether to act on the local certificate authority or one provided by a
+      remote puppet master. Allowed values are 'local' and 'remote.'
+    EOT
+
     before_action do |action, args, options|
       Puppet::SSL::Host.ca_location = options[:ca_location].to_sym
     end
   end
 
   action :generate do
-    summary "Generate a new Certificate Signing Request for HOST"
+    summary "Generate a new certificate signing request for HOST"
+    description <<-EOT
+      Generates and submits a certificate signing request (CSR) for the
+      provided host identifier. This CSR will then have to be signed by a user
+      with the proper authorization on the certificate authority.
+
+      Puppet agent handles CSR submission automatically. This action is
+      primarily useful for requesting certificates for individual users and
+      external applications.
+    EOT
 
     when_invoked do |name, options|
       host = Puppet::SSL::Host.new(name)
@@ -19,7 +55,7 @@ Puppet::Face::Indirector.define(:certificate, '0.0.1') do
   end
 
   action :list do
-    summary "List all Certificate Signing Requests"
+    summary "List all certificate signing requests"
 
     when_invoked do |options|
       Puppet::SSL::Host.indirection.search("*", {
@@ -29,7 +65,7 @@ Puppet::Face::Indirector.define(:certificate, '0.0.1') do
   end
 
   action :sign do
-    summary "Sign a Certificate Signing Request for HOST"
+    summary "Sign a certificate signing request for HOST"
 
     when_invoked do |name, options|
       host = Puppet::SSL::Host.new(name)
diff --git a/lib/puppet/face/certificate_request.rb b/lib/puppet/face/certificate_request.rb
index 1feba25ab..cc6021517 100644
--- a/lib/puppet/face/certificate_request.rb
+++ b/lib/puppet/face/certificate_request.rb
@@ -1,4 +1,32 @@
-require 'puppet/face/indirector'
+require 'puppet/indirector/face'
 
-Puppet::Face::Indirector.define(:certificate_request, '0.0.1') do
+Puppet::Indirector::Face.define(:certificate_request, '0.0.1') do
+  copyright "Puppet Labs", 2011
+  license   "Apache 2 license; see COPYING"
+
+  summary "Manage certificate requests."
+  description <<-EOT
+    Retrieves and submits certificate signing requests (CSRs). Invoke
+    `search` with an unread key to retrieve all outstanding CSRs, invoke
+    `find` with a node certificate name to retrieve a specific request, and
+    invoke `save` to submit a CSR.
+  EOT
+  notes <<-EOT
+    This is an indirector face, which exposes find, search, save, and
+    destroy actions for an indirected subsystem of Puppet. Valid terminuses
+    for this face include:
+
+    * `ca`
+    * `file`
+    * `rest`
+  EOT
+  examples <<-EOT
+    Retrieve all CSRs from the local CA:
+
+        puppet certificate_request search no_key --terminus ca
+
+    Retrieve a single CSR from the puppet master's CA:
+
+        puppet certificate_request find mynode.puppetlabs.lan --terminus rest
+  EOT
 end
diff --git a/lib/puppet/face/certificate_revocation_list.rb b/lib/puppet/face/certificate_revocation_list.rb
index 6a75aa578..2722b20f2 100644
--- a/lib/puppet/face/certificate_revocation_list.rb
+++ b/lib/puppet/face/certificate_revocation_list.rb
@@ -1,4 +1,30 @@
-require 'puppet/face/indirector'
+require 'puppet/indirector/face'
 
-Puppet::Face::Indirector.define(:certificate_revocation_list, '0.0.1') do
+Puppet::Indirector::Face.define(:certificate_revocation_list, '0.0.1') do
+  copyright "Puppet Labs", 2011
+  license   "Apache 2 license; see COPYING"
+
+  summary "Manage the list of revoked certificates."
+  description <<-EOT
+    This face is primarily for retrieving the certificate revocation
+    list from the CA. Although it exposes search/save/destroy methods,
+    they shouldn't be used under normal circumstances.
+  EOT
+  notes <<-EOT
+    Although the find action must be given an argument, this argument is
+    never read, and can contain the descriptive text of your choice.
+
+    This is an indirector face, which exposes find, search, save, and
+    destroy actions for an indirected subsystem of Puppet. Valid terminuses
+    for this face include:
+
+    * `ca`
+    * `file`
+    * `rest`
+  EOT
+  examples <<-EXAMPLES
+    Retrieve the CRL:
+
+        puppet certificate_revocation_list find crl
+  EXAMPLES
 end
diff --git a/lib/puppet/face/config.rb b/lib/puppet/face/config.rb
index 45cb6b156..9ca41085e 100644
--- a/lib/puppet/face/config.rb
+++ b/lib/puppet/face/config.rb
@@ -1,7 +1,43 @@
 require 'puppet/face'
 
 Puppet::Face.define(:config, '0.0.1') do
+  copyright "Puppet Labs", 2011
+  license   "Apache 2 license; see COPYING"
+
+  summary "Interact with Puppet configuration options"
+
   action(:print) do
+    summary "Examine Puppet's current configuration options"
+    description <<-EOT
+      Prints the value of a single configuration option or a list of
+      configuration options.
+
+      This action is an alternate interface to the information available with
+      `puppet agent --configprint`.
+    EOT
+    notes <<-EOT
+      The return data of this action varies depending on its arguments. When
+      called with "all," `print` will return a complete list of option names
+      and values. When called with a single configuration option name, it will
+      return the value of that option. When called with a list of
+      configuration option names, it will return the corresponding list of
+      option names and values.
+
+      By default, this action retrieves its configuration information in agent
+      mode. To examine the master's configuration, supply Puppet's global
+      `--mode master` option. To examine configurations from a specific
+      environment, you can use the `--environment` option.
+    EOT
+    examples <<-EOT
+      Get puppet's runfile directory:
+
+          puppet config print rundir
+
+      Get a list of important directories from the master's config:
+
+          puppet config print all --mode master | grep -E "(path|dir)"
+    EOT
+
     when_invoked do |*args|
       options = args.pop
       Puppet.settings[:configprint] = args.join(",")
diff --git a/lib/puppet/face/configurer.rb b/lib/puppet/face/configurer.rb
deleted file mode 100644
index 74dfb854e..000000000
--- a/lib/puppet/face/configurer.rb
+++ /dev/null
@@ -1,12 +0,0 @@
-require 'puppet/face'
-
-Puppet::Face.define(:configurer, '0.0.1') do
-  action(:synchronize) do
-    when_invoked do |certname, options|
-      facts = Puppet::Face[:facts, '0.0.1'].find(certname)
-      catalog = Puppet::Face[:catalog, '0.0.1'].download(certname, facts)
-      report = Puppet::Face[:catalog, '0.0.1'].apply(catalog)
-      report
-    end
-  end
-end
diff --git a/lib/puppet/face/facts.rb b/lib/puppet/face/facts.rb
index 04eab93a5..ecf4e371e 100644
--- a/lib/puppet/face/facts.rb
+++ b/lib/puppet/face/facts.rb
@@ -1,9 +1,40 @@
-require 'puppet/face/indirector'
+require 'puppet/indirector/face'
 require 'puppet/node/facts'
 
-Puppet::Face::Indirector.define(:facts, '0.0.1') do
-  # Upload our facts to the server
+Puppet::Indirector::Face.define(:facts, '0.0.1') do
+  copyright "Puppet Labs", 2011
+  license   "Apache 2 license; see COPYING"
+
+  summary "Retrieve, store, and view facts."
+  notes <<-EOT
+    This is an indirector face, which exposes find, search, save, and
+    destroy actions for an indirected subsystem of Puppet. Valid terminuses
+    for this face include:
+
+    * `active_record`
+    * `couch`
+    * `facter`
+    * `inventory_active_record`
+    * `memory`
+    * `network_device`
+    * `rest`
+    * `yaml`
+  EOT
+
   action(:upload) do
+    summary "Upload our facts to the puppet master."
+    description <<-EOT
+      Retrieves facts for the local system and saves them to the puppet master
+      server. This is essentially a shortcut action: it calls the `find`
+      action with the facter terminus, then passes the returned facts object
+      to the `save` action, which uses the rest terminus.
+    EOT
+    notes <<-EOT
+      This action uses the save action, which requires the puppet master's
+      auth.conf to allow save access to the `facts` REST terminus. See
+      `http://docs.puppetlabs.com/guides/rest_auth_conf.html` for more details.
+    EOT
+
     render_as :yaml
 
     when_invoked do |options|
diff --git a/lib/puppet/face/file.rb b/lib/puppet/face/file.rb
index 1aa9462dd..707ceafd4 100644
--- a/lib/puppet/face/file.rb
+++ b/lib/puppet/face/file.rb
@@ -1,5 +1,21 @@
-require 'puppet/face/indirector'
+require 'puppet/indirector/face'
+
+Puppet::Indirector::Face.define(:file, '0.0.1') do
+  copyright "Puppet Labs", 2011
+  license   "Apache 2 license; see COPYING"
+
+  summary "Retrieve and store files in a filebucket"
+  # TK this needs a description of how to find files in a filebucket, and
+  # some good use cases for retrieving/storing them. I can't write either
+  # of these yet.
+  notes <<-EOT
+    This is an indirector face, which exposes find, search, save, and
+    destroy actions for an indirected subsystem of Puppet. Valid terminuses
+    for this face include:
+
+    * `file`
+    * `rest`
+  EOT
 
-Puppet::Face::Indirector.define(:file, '0.0.1') do
   set_indirection_name :file_bucket_file
 end
diff --git a/lib/puppet/face/file/download.rb b/lib/puppet/face/file/download.rb
new file mode 100644
index 000000000..f5413d493
--- /dev/null
+++ b/lib/puppet/face/file/download.rb
@@ -0,0 +1,36 @@
+# Download a specified file into the local filebucket.
+Puppet::Face.define(:file, '0.0.1') do
+  action :download do |*args|
+    when_invoked do |sum, options|
+      if sum =~ /^puppet:\/\// # it's a puppet url
+        require 'puppet/file_serving'
+        require 'puppet/file_serving/content'
+        raise "Could not find metadata for #{sum}" unless content = Puppet::FileServing::Content.indirection.find(sum)
+        file = Puppet::FileBucket::File.new(content.content)
+      else
+        tester = Object.new
+        tester.extend(Puppet::Util::Checksums)
+
+        type    = tester.sumtype(sum)
+        sumdata = tester.sumdata(sum)
+
+        key = "#{type}/#{sumdata}"
+
+        Puppet::FileBucket::File.indirection.terminus_class = :file
+        if Puppet::FileBucket::File.indirection.find(key)
+          Puppet.info "Content for '#{sum}' already exists"
+          return
+        end
+
+        Puppet::FileBucket::File.indirection.terminus_class = :rest
+        raise "Could not download content for '#{sum}'" unless file = Puppet::FileBucket::File.indirection.find(key)
+      end
+
+
+      Puppet::FileBucket::File.indirection.terminus_class = :file
+      Puppet.notice "Saved #{sum} to filebucket"
+      Puppet::FileBucket::File.indirection.save file
+      return nil
+    end
+  end
+end
diff --git a/lib/puppet/face/file/store.rb b/lib/puppet/face/file/store.rb
new file mode 100644
index 000000000..4c9523b6c
--- /dev/null
+++ b/lib/puppet/face/file/store.rb
@@ -0,0 +1,12 @@
+# Store a specified file in our filebucket.
+Puppet::Face.define(:file, '0.0.1') do
+  action :store do |*args|
+    when_invoked do |path, options|
+      file = Puppet::FileBucket::File.new(File.read(path))
+
+      Puppet::FileBucket::File.indirection.terminus_class = :file
+      Puppet::FileBucket::File.indirection.save file
+      file.checksum
+    end
+  end
+end
diff --git a/lib/puppet/face/help.rb b/lib/puppet/face/help.rb
index a762fb02e..aef917447 100644
--- a/lib/puppet/face/help.rb
+++ b/lib/puppet/face/help.rb
@@ -4,13 +4,16 @@ require 'pathname'
 require 'erb'
 
 Puppet::Face.define(:help, '0.0.1') do
+  copyright "Puppet Labs", 2011
+  license   "Apache 2 license; see COPYING"
+
   summary "Displays help about puppet subcommands"
 
   action(:help) do
     summary "Display help about faces and their actions."
 
     option "--version VERSION" do
-      desc "Which version of the interface to show help for"
+      summary "which version of the interface to show help for"
     end
 
     default
@@ -21,29 +24,20 @@ Puppet::Face.define(:help, '0.0.1') do
       options = args.pop
       if options.nil? or args.length > 2 then
         if args.select { |x| x == 'help' }.length > 2 then
-          c = "\n !\"'),-./7:;<GIJLST\\_`abcdefhiklmnoprstuwx|}".split('')
+          c = "\n %'(),-./=ADEFHILORSTUXY\\_`gnv|".split('')
           i = <<-'EOT'.gsub(/\s*/, '').to_i(36)
-            2s7ytxy5vpj74kbab5xzf1ik2roinzlefaspjrzckiert5xbaxvwlku3a91w7y1rsd
-            nenp51gwpulmnrp54nwdil36fjgjarab801y0r5a9nh1hdfgi99arn5c5t3zhxbvzi
-            u6wx5r1tb7lun7pro69nrxunqqixsh6qmmv0ms0i0yycqw3pystyzmiita0lpxynqs
-            qkbjwadcx82n76wwpzbht8i8rgvqhqick8mk3cs3rvwdjookpgu0rxw4tcezned5sq
-            z5x8z9vntyyz0s4h6hjhtwtbytsmmu7ltvdftaixc7fkt276sqm48ab4yv0ot9y26n
-            z0xniy4pfl1x300lt6h9c8of49vf799ieuxwnoycsjlmtd4qntzit524j0tdn6n5aj
-            mq3z10apjuhkzprvmu53z1gnacymnoforrz5mbqto062kckgw5463pxwzg8liglub4
-            ubnr0dln1s6iy3ummxuhim7m5a7yedl3gyy6ow4qqtmsigv27lysooau24zpsccsvx
-            ddwygjprqpbwon7i9s1279m1fpinvva8mfh6bgmotrpxsh1c8rc83l3u0utf5i200y
-            l7ui0ngcbcjyr4erzdee2tqk3fpjvb82t8xhncruhgn7j5dh2m914qzhb0gkoom47k
-            6et7rp4tqjnrv0y2apk5qdl1x1hnbkkxup5ys6ip2ksmtpd3ipmrdtswxr5xwfiqtm
-            60uyjr1v79irhnkrbbt4fwhgqjby1qflgwt9c1wpayzzucep6npgbn3f1k6cn4pug3
-            1u02wel4tald4hij8m5p49xr8u4ero1ucs5uht42o8nhpmpe7c7xf9t85i85m9m5kk
-            tgoqkgbu52gy5aoteyp8jkm3vri9fnkmwa5h60zt8otja72joxjb40p2rz2vp8f8q9
-            nnggxt3x90pe5u4048ntyuha78q1oikhhpvw9j083yc3l00hz5ehv9c1au5gvctyap
-            zprub289qruve9qsyuh75j04wzkemqw3uhisrfs92u1ahv2qlqxmorgob16c1vbqkx
-            ttkoyp2agkt0v5l7lec25p0jqun9y39k41h67aeb5ihiqsftxc9azmg31hc73dk8ur
-            lj88vgbmgt8yln9rchw60whgxvnv9zn6cxbr482svctswc5a07atj
+            3he6737w1aghshs6nwrivl8mz5mu9nywg9tbtlt081uv6fq5kvxse1td3tj1wvccmte806nb
+            cy6de2ogw0fqjymbfwi6a304vd56vlq71atwmqsvz3gpu0hj42200otlycweufh0hylu79t3
+            gmrijm6pgn26ic575qkexyuoncbujv0vcscgzh5us2swklsp5cqnuanlrbnget7rt3956kam
+            j8adhdrzqqt9bor0cv2fqgkloref0ygk3dekiwfj1zxrt13moyhn217yy6w4shwyywik7w0l
+            xtuevmh0m7xp6eoswin70khm5nrggkui6z8vdjnrgdqeojq40fya5qexk97g4d8qgw0hvokr
+            pli1biaz503grqf2ycy0ppkhz1hwhl6ifbpet7xd6jjepq4oe0ofl575lxdzjeg25217zyl4
+            nokn6tj5pq7gcdsjre75rqylydh7iia7s3yrko4f5ud9v8hdtqhu60stcitirvfj6zphppmx
+            7wfm7i9641d00bhs44n6vh6qvx39pg3urifgr6ihx3e0j1ychzypunyou7iplevitkyg6gbg
+            wm08oy1rvogcjakkqc1f7y1awdfvlb4ego8wrtgu9vzw4vmj59utwifn2ejcs569dh1oaavi
+            sc581n7jjg1dugzdu094fdobtx6rsvk3sfctvqnr36xctold
           EOT
-          607.times{i,x=i.divmod(1035);a,b=x.divmod(23);print(c[a]*b)}
-          raise ArgumentError, "Such panic is really not required."
+          353.times{i,x=i.divmod(1184);a,b=x.divmod(37);print(c[a]*b)}
         end
         raise ArgumentError, "help only takes two (optional) arguments, a face name, and an action"
       end
diff --git a/lib/puppet/face/help/action.erb b/lib/puppet/face/help/action.erb
index eaf131464..c26958a35 100644
--- a/lib/puppet/face/help/action.erb
+++ b/lib/puppet/face/help/action.erb
@@ -1,3 +1,48 @@
-Use: puppet <%= face.name %> [options] <%= action.name %> [options]
+puppet <%= face.name %><%= action.default? ? '' : " #{action.name}" %>(1) -- <%= action.summary || face.summary %>
+<%= '=' * (_erbout.length - 1) %>
 
-Summary: <%= action.summary %>
+% if action.synopsis
+SYNOPSIS
+--------
+
+<%= action.synopsis %>
+
+% end
+% if action.description
+DESCRIPTION
+-----------
+<%= action.description %>
+
+%end
+% unless action.options.empty?
+OPTIONS
+-------
+%   action.options.sort.each do |name|
+%     option = action.get_option name
+<%= "  " + option.optparse.join(" |" ) %>
+<%= option.summary %>
+<%= option.description %>
+
+%   end
+% end
+% if action.examples
+EXAMPLES
+--------
+<%= action.examples %>
+% end
+% if action.notes
+NOTES
+-----
+<%= action.notes %>
+
+% end
+% unless action.authors.empty?
+AUTHOR
+------
+<%= action.authors.map {|x| " * " + x } .join("\n") %>
+
+%end
+COPYRIGHT AND LICENSE
+---------------------
+<%= action.copyright %>
+<%= action.license   %>
diff --git a/lib/puppet/face/help/face.erb b/lib/puppet/face/help/face.erb
index efe5fd809..b249981de 100644
--- a/lib/puppet/face/help/face.erb
+++ b/lib/puppet/face/help/face.erb
@@ -1,7 +1,48 @@
-Use: puppet <%= face.name %> [options] <action> [options]
+NAME
+  <%= face.name %> -- <%= face.summary || "unknown face..." %>
 
-Available actions:
+% if face.synopsis
+SYNOPSIS
+<%= face.synopsis.gsub(/^/, '  ') %>
+
+% end
+% if face.description
+DESCRIPTION
+<%= face.description.chomp.gsub(/^/, '  ') %>
+
+%end
+% unless face.options.empty?
+OPTIONS
+%   face.options.sort.each do |name|
+%     option = face.get_option name
+<%= "  " + option.optparse.join(" |" ) %>
+<%= option.summary %>
+<%= option.description %>
+
+%   end
+% end
+ACTIONS
+% padding = face.actions.map{|x| x.to_s.length}.max + 2
 % face.actions.each do |actionname|
 %   action = face.get_action(actionname)
-  <%= action.name.to_s.ljust(16) %>  <%= action.summary %>
+  <%= action.name.to_s.ljust(padding) %>  <%= action.summary %>
 % end
+
+% if face.examples
+EXAMPLES
+<%= face.examples %>
+% end
+% if face.notes
+NOTES
+<%= face.notes %>
+
+% end
+% unless face.authors.empty?
+AUTHOR
+<%= face.authors.join("\n").gsub(/^/, ' * ') %>
+
+%end
+COPYRIGHT AND LICENSE
+<%= face.copyright.gsub(/^/, '  ') %>
+<%= face.license.gsub(/^/, '  ')   %>
+
diff --git a/lib/puppet/face/help/global.erb b/lib/puppet/face/help/global.erb
index f4c761b2b..80c77ad26 100644
--- a/lib/puppet/face/help/global.erb
+++ b/lib/puppet/face/help/global.erb
@@ -1,4 +1,4 @@
-puppet <subcommand> [options] <action> [options]
+Usage: puppet <subcommand> [options] <action> [options]
 
 Available subcommands, from Puppet Faces:
 % Puppet::Face.faces.sort.each do |name|
@@ -16,5 +16,4 @@ Available applications, soon to be ported to Faces:
 
 See 'puppet help <subcommand> <action>' for help on a specific subcommand action.
 See 'puppet help <subcommand>' for help on a specific subcommand.
-See 'puppet man  <subcommand>' for the full man page.
 Puppet v<%= Puppet::PUPPETVERSION %>
diff --git a/lib/puppet/face/indirector.rb b/lib/puppet/face/indirector.rb
deleted file mode 100644
index 6c7708b51..000000000
--- a/lib/puppet/face/indirector.rb
+++ /dev/null
@@ -1,95 +0,0 @@
-require 'puppet'
-require 'puppet/face'
-
-class Puppet::Face::Indirector < Puppet::Face
-  option "--terminus TERMINUS" do
-    desc "REVISIT: You can select a terminus, which has some bigger effect
-that we should describe in this file somehow."
-
-    before_action do |action, args, options|
-      set_terminus(options[:terminus])
-    end
-
-    after_action do |action, args, options|
-      indirection.reset_terminus_class
-    end
-  end
-
-  def self.indirections
-    Puppet::Indirector::Indirection.instances.collect { |t| t.to_s }.sort
-  end
-
-  def self.terminus_classes(indirection)
-    Puppet::Indirector::Terminus.terminus_classes(indirection.to_sym).collect { |t| t.to_s }.sort
-  end
-
-  def call_indirection_method(method, *args)
-    options = args.last
-
-    begin
-      result = indirection.__send__(method, *args)
-    rescue => detail
-      puts detail.backtrace if Puppet[:trace]
-      raise "Could not call '#{method}' on '#{indirection_name}': #{detail}"
-    end
-
-    return result
-  end
-
-  action :destroy do
-    when_invoked { |*args| call_indirection_method(:destroy, *args) }
-  end
-
-  action :find do
-    when_invoked { |*args| call_indirection_method(:find, *args) }
-  end
-
-  action :save do
-    when_invoked { |*args| call_indirection_method(:save, *args) }
-  end
-
-  action :search do
-    when_invoked { |*args| call_indirection_method(:search, *args) }
-  end
-
-  # Print the configuration for the current terminus class
-  action :info do
-    when_invoked do |*args|
-      if t = indirection.terminus_class
-        puts "Run mode '#{Puppet.run_mode.name}': #{t}"
-      else
-        $stderr.puts "No default terminus class for run mode '#{Puppet.run_mode.name}'"
-      end
-    end
-  end
-
-  attr_accessor :from
-
-  def indirection_name
-    @indirection_name || name.to_sym
-  end
-
-  # Here's your opportunity to override the indirection name.  By default it
-  # will be the same name as the face.
-  def set_indirection_name(name)
-    @indirection_name = name
-  end
-
-  # Return an indirection associated with a face, if one exists;
-  # One usually does.
-  def indirection
-    unless @indirection
-      @indirection = Puppet::Indirector::Indirection.instance(indirection_name)
-      @indirection or raise "Could not find terminus for #{indirection_name}"
-    end
-    @indirection
-  end
-
-  def set_terminus(from)
-    begin
-      indirection.terminus_class = from
-    rescue => detail
-      raise "Could not set '#{indirection.name}' terminus to '#{from}' (#{detail}); valid terminus types are #{self.class.terminus_classes(indirection.name).join(", ") }"
-    end
-  end
-end
diff --git a/lib/puppet/face/key.rb b/lib/puppet/face/key.rb
index 3a11ddb03..67d775ca4 100644
--- a/lib/puppet/face/key.rb
+++ b/lib/puppet/face/key.rb
@@ -1,4 +1,23 @@
-require 'puppet/face/indirector'
+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
+    Keys are created for you automatically when certificate requests are
+    generated with 'puppet certificate generate'. You should not have to use
+    this action directly from the command line.
+  EOT
+  notes <<-EOT
+    This is an indirector face, which exposes find, search, save, and
+    destroy actions for an indirected subsystem of Puppet. Valid terminuses
+    for this face include:
+
+    * `ca`
+    * `file`
+  EOT
 
-Puppet::Face::Indirector.define(:key, '0.0.1') do
 end
diff --git a/lib/puppet/face/node.rb b/lib/puppet/face/node.rb
index 12336df8f..be38ad388 100644
--- a/lib/puppet/face/node.rb
+++ b/lib/puppet/face/node.rb
@@ -1,3 +1,26 @@
-require 'puppet/face/indirector'
-Puppet::Face::Indirector.define(:node, '0.0.1') do
+require 'puppet/indirector/face'
+Puppet::Indirector::Face.define(:node, '0.0.1') do
+  copyright "Puppet Labs", 2011
+  license   "Apache 2 license; see COPYING"
+
+  summary "View and manage node definitions"
+
+  description <<-EOT
+    This face interacts with node objects, which are what Puppet uses to
+    build a catalog. A node object consists of the node's facts,
+    environment, additional top-scope variables, and classes.
+  EOT
+  notes <<-EOT
+    This is an indirector face, which exposes find, search, save, and
+    destroy actions for an indirected subsystem of Puppet. Valid terminuses
+    for this face include:
+
+    * `active_record`
+    * `exec`
+    * `ldap`
+    * `memory`
+    * `plain`
+    * `rest`
+    * `yaml`
+  EOT
 end
diff --git a/lib/puppet/face/parser.rb b/lib/puppet/face/parser.rb
index d4aaaf043..e6a9503dd 100644
--- a/lib/puppet/face/parser.rb
+++ b/lib/puppet/face/parser.rb
@@ -2,19 +2,30 @@ require 'puppet/face'
 require 'puppet/parser'
 
 Puppet::Face.define(:parser, '0.0.1') do
- action :validate do
-   when_invoked do |*args|
-     args.pop
-     files = args
-     if files.empty?
-       files << Puppet[:manifest]
-       Puppet.notice "No manifest specified. Validating the default manifest #{Puppet[:manifest]}"
-     end
-     files.each do |file|
-       Puppet[:manifest] = file
-       Puppet::Node::Environment.new(Puppet[:environment]).known_resource_types.clear
-     end
-     nil
-   end
- end
+  copyright "Puppet Labs", 2011
+  license   "Apache 2 license; see COPYING"
+
+  summary "Interact directly with the parser"
+
+  action :validate do
+    summary "Validate the syntax of one or more Puppet manifests"
+    description <<-EOT
+      This action validates Puppet DSL syntax without compiling a catalog or
+      syncing any resources. If no manifest files are provided, it will
+      validate the default site manifest.
+    EOT
+    when_invoked do |*args|
+      args.pop
+      files = args
+      if files.empty?
+        files << Puppet[:manifest]
+        Puppet.notice "No manifest specified. Validating the default manifest #{Puppet[:manifest]}"
+      end
+      files.each do |file|
+        Puppet[:manifest] = file
+        Puppet::Node::Environment.new(Puppet[:environment]).known_resource_types.clear
+      end
+      nil
+    end
+  end
 end
diff --git a/lib/puppet/face/plugin.rb b/lib/puppet/face/plugin.rb
new file mode 100644
index 000000000..969d42389
--- /dev/null
+++ b/lib/puppet/face/plugin.rb
@@ -0,0 +1,47 @@
+require 'puppet/face'
+Puppet::Face.define(:plugin, '0.0.1') do
+  copyright "Puppet Labs", 2011
+  license   "Apache 2 license; see COPYING"
+
+  summary "Interact with the Puppet plugin system"
+  description <<-EOT
+    This face provides network access to the puppet master's store of
+    plugins. It is intended for use in other faces, rather than for direct
+    command line access.
+  EOT
+  notes <<-EOT
+    The puppet master can serve Ruby code collected from the lib directories
+    of its modules. These plugins can be used on agent nodes to extend
+    Facter and implement custom types and providers.
+  EOT
+
+  action :download do
+    summary "Download plugins from the configured master"
+    returns <<-EOT
+      An array containing the files actually downloaded. If all files
+      were in sync, this array will be empty.
+    EOT
+    notes "This action modifies files on disk without returning any data."
+    examples <<-EOT
+      Retrieve plugins from the puppet master:
+
+          Puppet::Face[:plugin, '0.0.1'].download
+    EOT
+
+    when_invoked do |options|
+      require 'puppet/configurer/downloader'
+      Puppet::Configurer::Downloader.new("plugin",
+                                         Puppet[:plugindest],
+                                         Puppet[:pluginsource],
+                                         Puppet[:pluginsignore]).evaluate
+    end
+
+    when_rendering :console do |value|
+      if value.empty? then
+        "No plugins downloaded."
+      else
+        "Downloaded these plugins: #{value.join(', ')}"
+      end
+    end
+  end
+end
diff --git a/lib/puppet/face/report.rb b/lib/puppet/face/report.rb
index 6e6f0b335..c8549b14f 100644
--- a/lib/puppet/face/report.rb
+++ b/lib/puppet/face/report.rb
@@ -1,11 +1,43 @@
-require 'puppet/face/indirector'
+require 'puppet/indirector/face'
+
+Puppet::Indirector::Face.define(:report, '0.0.1') do
+  copyright "Puppet Labs", 2011
+  license   "Apache 2 license; see COPYING"
+
+  summary "Create, display, and submit reports"
+  notes <<-EOT
+    This is an indirector face, which exposes find, search, save, and
+    destroy actions for an indirected subsystem of Puppet. Valid terminuses
+    for this face include:
+
+    * `processor`
+    * `rest`
+    * `yaml`
+  EOT
 
-Puppet::Face::Indirector.define(:report, '0.0.1') do
   action(:submit) do
+    summary "Submit a report object to the puppet master"
+    description <<-EOT
+      This action is essentially a shortcut and wrapper for the `save` action
+      with a terminus of `rest`. It also can provide additional details in the
+      event of a report submission failure. It is not intended for use from
+      a command line.
+    EOT
+    examples <<-EOT
+      From secret_agent.rb:
+          Puppet::Face[:plugin, '0.0.1'].download
+
+          facts   = Puppet::Face[:facts, '0.0.1'].find(certname)
+          catalog = Puppet::Face[:catalog, '0.0.1'].download(certname, facts)
+          report  = Puppet::Face[:catalog, '0.0.1'].apply(catalog)
+
+          Puppet::Face[:report, '0.0.1'].submit(report)
+    EOT
     when_invoked do |report, options|
       begin
-        Puppet::Transaction::Report.terminus_class = :rest
-        report.save
+        Puppet::Transaction::Report.indirection.terminus_class = :rest
+        Puppet::Face[:report, "0.0.1"].save(report)
+        Puppet.notice "Uploaded report for #{report.name}"
       rescue => detail
         puts detail.backtrace if Puppet[:trace]
         Puppet.err "Could not send report: #{detail}"
diff --git a/lib/puppet/face/resource.rb b/lib/puppet/face/resource.rb
index d162f728a..ed6360888 100644
--- a/lib/puppet/face/resource.rb
+++ b/lib/puppet/face/resource.rb
@@ -1,4 +1,23 @@
-require 'puppet/face/indirector'
+require 'puppet/indirector/face'
 
-Puppet::Face::Indirector.define(:resource, '0.0.1') do
+Puppet::Indirector::Face.define(:resource, '0.0.1') do
+  copyright "Puppet Labs", 2011
+  license   "Apache 2 license; see COPYING"
+
+  summary "Interact directly with resources via the RAL, like ralsh"
+  description <<-EOT
+    This face provides a Ruby API with functionality similar to the puppet
+    resource (née ralsh) command line application. It is not intended to be
+    used from the command line.
+  EOT
+  notes <<-EOT
+    This is an indirector face, which exposes find, search, save, and
+    destroy actions for an indirected subsystem of Puppet. Valid terminuses
+    for this face include:
+
+    * `ral`
+    * `rest`
+  EOT
+
+  examples "TK we really need some examples for this one."
 end
diff --git a/lib/puppet/face/resource_type.rb b/lib/puppet/face/resource_type.rb
index 0cdbd719f..77ccefa8f 100644
--- a/lib/puppet/face/resource_type.rb
+++ b/lib/puppet/face/resource_type.rb
@@ -1,4 +1,17 @@
-require 'puppet/face/indirector'
+require 'puppet/indirector/face'
 
-Puppet::Face::Indirector.define(:resource_type, '0.0.1') do
+Puppet::Indirector::Face.define(:resource_type, '0.0.1') do
+  copyright "Puppet Labs", 2011
+  license   "Apache 2 license; see COPYING"
+
+  summary "View resource types, classes, and nodes from all manifests"
+  description "TK I have no idea what this does."
+  notes <<-EOT
+    This is an indirector face, which exposes find, search, save, and
+    destroy actions for an indirected subsystem of Puppet. Valid terminuses
+    for this face include:
+
+    * `parser`
+    * `rest`
+  EOT
 end
diff --git a/lib/puppet/face/secret_agent.rb b/lib/puppet/face/secret_agent.rb
new file mode 100644
index 000000000..c8c8e6629
--- /dev/null
+++ b/lib/puppet/face/secret_agent.rb
@@ -0,0 +1,39 @@
+require 'puppet/face'
+
+Puppet::Face.define(:secret_agent, '0.0.1') do
+  copyright "Puppet Labs", 2011
+  license   "Apache 2 license; see COPYING"
+
+  summary "Provides agent-like behavior, with no plugin downloading or reporting"
+  description <<-EOT
+    This face currently functions as a proof of concept, demonstrating how
+    Faces allows the separation of application logic from Puppet's internal
+    systems; compare the code for puppet agent. It will eventually replace
+    puppet agent entirely, and can provide a template for users who wish to
+    implement agent-like functionality with drastically different
+    application logic.
+  EOT
+
+  action(:synchronize) do
+    summary "Retrieve and apply a catalog from the puppet master"
+    description <<-EOT
+      This action mimics the behavior of the puppet agent application. It does
+      not currently daemonize, but can download plugins, submit facts,
+      retrieve and apply a catalog, and submit a report to the puppet master.
+    EOT
+
+    when_invoked do |options|
+      Puppet::Face[:plugin, '0.0.1'].download
+
+      Puppet::Face[:facts, '0.0.1'].upload
+
+      Puppet::Face[:catalog, '0.0.1'].download
+
+      report  = Puppet::Face[:catalog, '0.0.1'].apply
+
+      Puppet::Face[:report, '0.0.1'].submit(report)
+
+      return report
+    end
+  end
+end
diff --git a/lib/puppet/face/status.rb b/lib/puppet/face/status.rb
index 7085e7cd7..6a29debdd 100644
--- a/lib/puppet/face/status.rb
+++ b/lib/puppet/face/status.rb
@@ -1,4 +1,30 @@
-require 'puppet/face/indirector'
+require 'puppet/indirector/face'
 
-Puppet::Face::Indirector.define(:status, '0.0.1') do
+Puppet::Indirector::Face.define(:status, '0.0.1') do
+  copyright "Puppet Labs", 2011
+  license   "Apache 2 license; see COPYING"
+
+  summary "View puppet server status"
+  description <<-EOT
+    This subcommand is only useful for determining whether a puppet master
+    server (or an agent node, if puppet was started with the `--listen`
+    option) is responding to requests.
+
+    Only the `find` action is valid. If the server is responding to
+    requests, `find` will retrieve a status object; if not, the connection
+    will be refused. When invoked with the `local` terminus, `find` will
+    always return true.
+
+    If you wish to query a server other than the master configured in
+    puppet.conf, you must set the `--server` and `--masterport` options on
+    the command line.
+  EOT
+  notes <<-EOT
+    This is an indirector face, which exposes find, search, save, and
+    destroy actions for an indirected subsystem of Puppet. Valid terminuses
+    for this face include:
+
+    * `local`
+    * `rest`
+  EOT
 end