devstructure 0.1.8 → 0.2.0

data/lib/devstructure/api.rb

@@ -1,7 +1,10 @@
+# The [DevStructure API](http://docs.devstructure.com/api) allows
+# read and write access to blueprints, and soon other parts of the
+# service.
 require 'devstructure'
 require 'devstructure/blueprint'
 
-# HERE BE DRAGONS The 1.4.3 version of the JSON gem is crap-tastic,
+# *HERE BE DRAGONS* The 1.4.3 version of the JSON gem is crap-tastic,
 # which forces me to pin to 1.4.2, which in turn forces me to load
 # RubyGems manually here, which in turn pretty much makes me cry.
 require 'rubygems'
@@ -13,13 +16,19 @@ require 'net/https'
 require 'openssl'
 require 'uri'
 
+# We subclass `Net::HTTP` so as not to take away a user's ability to
+# shoot themselves in the foot.
 class DevStructure::API < Net::HTTP
 
-  # Undo Net::HTTP's allocator hijacking.
+  # Undo `Net::HTTP`'s allocator hijacking.
   class << self
     alias new newobj
   end
 
+  # No one really has access to a DevStructure API token these days,
+  # save for the one that's installed on each DevStructure server.
+  # The default token is the one created by concatenating `/etc/token`
+  # and `~/.token`.
   def initialize(token=nil)
     @newimpl = true
     uri = URI.parse("https://api.devstructure.com")
@@ -38,11 +47,15 @@ class DevStructure::API < Net::HTTP
     end
   end
 
+  # This is the lazy man's way of building the URI for a request.
   def path(*args)
     args.reject! { |arg| arg.nil? }
     "/#{args.join("/")}"
   end
 
+  # These are the only two headers that are required when accessing the
+  # API.  Others such as `Content-Type` and `Content-Length` will be
+  # added as necessary, either explicitly or by `Net::HTTP`.
   def headers
     {
       "Authorization" => "Token token=\"#{@token}\"",
@@ -50,14 +63,22 @@ class DevStructure::API < Net::HTTP
     }
   end
 
+  # `Blueprints` objects represent a particular user's blueprint collection
+  # but is supremely lazy about fetching it.
   class Blueprints
     include DevStructure
 
+    # This ugly constructor should be eschewed in favor of `API#blueprints`.
     def initialize(api, username=nil)
       @api = api
       @username = username
     end
 
+    # The `method_missing` handler allows natural-looking code like
+    # `blueprints.foo.bar` that look like the URIs they're referencing
+    # behind the scenes.  These are limited to reads when taken all the
+    # way to referencing a specific blueprint.  Just referencing a user
+    # this way still allows writes.
     def method_missing(symbol, *args)
       if @username
         get symbol.to_s
@@ -67,6 +88,9 @@ class DevStructure::API < Net::HTTP
       end
     end
 
+    # The API version of
+    # [`blueprint-list`(1)](http://devstructure.github.com/contractor/blueprint-list.1.html).
+    # It returns an array of `DevStructure::Blueprint` objects.
     def list
       @api.start unless @api.started?
       response = @api.get(@api.path("blueprints", @username), @api.headers)
@@ -76,6 +100,9 @@ class DevStructure::API < Net::HTTP
       end
     end
 
+    # The API version of
+    # [`blueprint-show`(1)](http://devstructure.github.com/contractor/blueprint-show.1.html).
+    # It returns a `DevStructure::Blueprint` object.
     def get(name, token=nil)
       @api.start unless @api.started?
       response = @api.get(@api.path("blueprints", @username, name, token),
@@ -85,6 +112,12 @@ class DevStructure::API < Net::HTTP
       Blueprint.new(hash["name"], hash)
     end
 
+    # The API version of
+    # [`blueprint-create`(1)](http://devstructure.github.com/contractor/blueprint-create.1.html).
+    # It encodes and POSTs a blueprint and uploads to S3 any source tarballs
+    # referenced.  The S3 upload credentials come back as part of the API
+    # response.  Each set of headers is only valid for that particular
+    # upload and even then only for a few minutes.
     def post(name, options={})
       @api.start unless @api.started?
       params = {}
@@ -113,6 +146,7 @@ class DevStructure::API < Net::HTTP
       response
     end
 
+    # Delete a blueprint and all its versions.
     def delete(name, options={})
       @api.start unless @api.started?
       @api.delete(@api.path("blueprints", @username, name), @api.headers)
@@ -120,6 +154,7 @@ class DevStructure::API < Net::HTTP
 
   end
 
+  # Grab a particular user's blueprint collection.
   def blueprints(username=nil)
     Blueprints.new(self, username)
   end

data/lib/devstructure/blueprint.rb

@@ -1,13 +1,20 @@
+# A `Blueprint` is just a `Hash` with some convenient additions, the first
+# of which is a set of instance methods that access the innards of the
+# blueprint itself (rather than the metadata).  `Blueprint`s come from
+# `DevStructure::API` and can actually save themselves if changes are made.
 require 'devstructure'
 require 'devstructure/api'
+require 'devstructure/chef'
 require 'devstructure/puppet'
 
 require 'base64'
+require 'stringio'
 
 class DevStructure::Blueprint < Hash
   include DevStructure
-  include DevStructure::Puppet
 
+  # Blueprints are usually created from a name and a hash, being gathered
+  # from the URL and response of a DevStructure API request.
   def initialize(name, hash)
     super nil
     clear
@@ -18,37 +25,61 @@ class DevStructure::Blueprint < Hash
 
   attr_accessor :name
 
+  # Attempt to save the blueprint, returning directly from the API.  This
+  # is purely for convenience.
   def save(ds=nil)
     ds ||= API.new
     ds.blueprints(owner).post(name, self)
   end
 
+  # The outer layers of the hash are not arbitrarily settable.  Blueprints
+  # have a defined set of fields and accepting anything beyond that would
+  # be confusing.
   private :[]=
 
+  # This is the preferred method for reading the blueprint metadata but
+  # hash-like access will work just fine, you'll just have to use strings.
   def method_missing(symbol, *args)
     self[symbol.to_s]
   end
 
+  # The architecture of the server used to create a blueprint will be
+  # "amd64" or "i386" if it's set at all.  When possible, the architecture
+  # is left unspecified to allow blueprints to be applied to any server.
   def arch
     self["blueprint"]["_arch"]
   end
 
+  # The files, packages, and sources hashes are completely described in
+  # [`blueprint`(5)](http://devstructure.github.com/contractor/blueprint.5.html).
   def files
     self["blueprint"]["_files"]
   end
-
   def packages
     self["blueprint"]["_packages"]
   end
-
   def sources
     self["blueprint"]["_sources"]
   end
 
+  # Subtracting one blueprint from another is an important strategy used
+  # to keep superfluous packages managed by `apt` out of blueprints in
+  # most cases.  Improvements in the 1.1.0 release reduced the need for
+  # this optimization but it doesn't hurt.
+  #
+  # It takes three passes through the package tree.  The first two
+  # remove superfluous packages and the final one accounts for some
+  # special dependencies by adding them back.
   def -(other)
     b = Marshal.load(Marshal.dump(self))
 
-    # First pass removes all duplicates except managers.
+    # The first pass removes all duplicate packages that are not
+    # themselves managers.  The introduction of multiple-version
+    # complicates this slightly.  For each package, each version
+    # that appears in the other blueprint is removed from this
+    # blueprint.  After that is finished, this blueprint is
+    # normalized.  If no versions remain, the package is removed.
+    # If only one version remains, it is converted to a string.
     other.walk(
       :package => lambda { |manager, command, package, version|
         return if b.packages[package]
@@ -66,7 +97,8 @@ class DevStructure::Blueprint < Hash
       }
     )
 
-    # Second pass removes managers that manage no packages.
+    # The second pass removes managers that manage no packages, which
+    # is a potential side effect of the first pass.
     b.walk(
       :package => lambda { |manager, command, package, version|
         return unless b.packages[package]
@@ -75,12 +107,19 @@ class DevStructure::Blueprint < Hash
       }
     )
 
-    # Third pass adds back special dependencies like ruby*-dev.
+    # The third pass adds back special dependencies like `ruby*-dev`.
+    # It isn't apparent by the rules above that a manager like RubyGems
+    # needs more than just itself to function.  In some sense, this
+    # might be considered a missing dependency in the Debian archive
+    # but in reality, it's only _likely_ that you need `ruby*-dev` to
+    # use `rubygems*`.
+    #
+    # The only dependency that fits this bill currently is in fact
+    # RubyGems, which gets `ruby*-dev` added for the matching version
+    # of the Ruby language.
     b.walk(
       :after => lambda { |manager, command|
         case manager
-
-        # Match a version of ruby*-dev to a version of rubygems*.
         when /^rubygems(\d+\.\d+(?:\.\d+)?)$/
           b.packages["apt"]["_packages"]["ruby#{$1}-dev"] =
             packages["apt"]["_packages"]["ruby#{$1}-dev"]
@@ -92,32 +131,47 @@ class DevStructure::Blueprint < Hash
     b
   end
 
+  # Everyone loves a good disclaimer.  This one's chock full of useful
+  # links so folks can find their way back to DevStructure when the
+  # need strikes.  Marketing!
   def disclaimer
-    puts <<EOF
-#
-# #{owner}'s #{name}
-# http#{token ? "s" : ""}://devstructure.com/blueprints/#{owner}/#{name}
+    disclaimer = <<EOF
+\#
+\# #{owner}'s #{name}
+\# http#{token ? "s" : ""}://devstructure.com/blueprints/#{owner}/#{name}
 EOF
     if token
-      puts <<EOF
-#
-# This blueprint is private.  You may share it by adding trusted users
-# or by sharing this secret URL:
-#   https://devstructure.com/blueprints/#{owner}/#{name}/#{token}
+      disclaimer << <<EOF
+\#
+\# This blueprint is private.  You may share it by adding trusted users
+\# or by sharing this secret URL:
+\#   https://devstructure.com/blueprints/#{owner}/#{name}/#{token}
 EOF
     end
-    puts <<EOF
-#
-# This file was automatically generated by ruby-devstructure(7).
-#
+    disclaimer << <<EOF
+\#
+\# This file was automatically generated by ruby-devstructure(7).
+\#
 EOF
+    disclaimer
   end
 
+  # This is the POSIX shell code generator.
   def sh
-    disclaimer
-
-    # Packages.
+    puts disclaimer
+
+    # First come packages.  The algorithm used to walk the package tree
+    # is pluggable and in this case we only need to take action as each
+    # package name is encountered.  Each manager is annotated with a
+    # shell command suitable for installing packages in `printf`(3)-style.
+    #
+    # RubyGems is, once again, a special case.  Ubuntu ships with a very
+    # old version so we take the liberty of upgrading it anytime it is
+    # encountered.
     walk(
+      :before => lambda { |manager, command|
+        puts "apt-get update" if "apt" == manager
+      },
       :package => lambda { |manager, command, package, version|
         return if manager == package
         printf "#{command}\n", package, version
@@ -129,7 +183,9 @@ EOF
       }
     )
 
-    # System files.
+    # Plaintext files are written to their final destination using `cat`(1)
+    # and heredoc syntax.  Binary files are written using `base64`(1) and
+    # symbolic links are placed using `ln`(1).  Shocking stuff.
     files.sort.each do |pathname, content|
       if Hash == content.class
         if content["_target"]
@@ -146,12 +202,15 @@ EOF
       end
       eof = "EOF"
       eof << "EOF" while content =~ /^#{eof}$/
+      puts "mkdir -p #{File.dirname(pathname)}"
       puts "#{command} >#{pathname} <<#{eof}"
       puts content
       puts eof
     end if files
 
-    # Source tarballs.
+    # Source tarballs are downloaded, extracted, and removed.  Generally,
+    # the directory in question is `/usr/local` but the future could hold
+    # anything.
     sources.sort.each do |dirname, filename|
       puts "wget http://s3.amazonaws.com/blueprint-sources/#{filename}"
       puts "tar xf #{filename} -C #{dirname}"
@@ -160,111 +219,155 @@ EOF
 
   end
 
+  # This is the Puppet code generator.
   def puppet
-    disclaimer
-    manifest = Manifest.new(@name)
-    manifest << Exec.defaults(:path => ENV["PATH"].split(":"))
+    puts disclaimer
+    manifest = Puppet::Manifest.new(@name)
+
+    # Right out of the gate, we set a default `PATH` because Puppet does not.
+    manifest << Puppet::Exec.defaults(:path => ENV["PATH"].split(":"))
 
-    # Map managers to their manager.
+    # We need a pre-built map of each manager to its own manager so we can
+    # easily declare dependencies within the Puppet manifest tree.
     managers = {}
     walk(:package => lambda { |manager, command, package, version|
       managers[package] = manager if packages[package] && manager != package
     })
 
-    # Packages.
+    # Each manager's packages are grouped to create a series of subclasses
+    # that allow dependency management to be handled coursely using Puppet
+    # classes.  Because of Puppet's rules about resource name uniqueness,
+    # we have to check that managers aren't managing themselves and bail
+    # early.
+    #
+    # As always, RubyGems is getting ready to get bossy so we're prepared
+    # by having the version of Ruby in question available.
     walk(
       :before => lambda { |manager, command|
         p = packages[manager]["_packages"]
         return if 0 == p.length || 1 == p.length && p[manager]
+        if "apt" == manager
+          manifest << Puppet::Exec.new("apt-get update",
+            :before => Puppet::Class["apt"])
+        end
       },
       :package => lambda { |manager, command, package, version|
         command =~ /gem(\d+\.\d+(?:\.\d+)?) install/
         ruby_version = $1
         case manager
 
+        # `apt` packages are natively supported by Puppet so they're
+        # very easy.
         when "apt"
           unless manager == package
-            manifest[manager] << Package.new(package, :ensure => version)
+            manifest[manager] << Puppet::Package.new(package,
+              :ensure => version
+            )
           end
 
-          # Update RubyGems.
+          # However, if this package happens to be RubyGems, we introduce
+          # a couple of new resources that update it to the latest version.
           if package =~ /^rubygems(\d+\.\d+(?:\.\d+)?)$/
             v = $1
             prereq = if "1.8" == v
-              manifest[manager] << Package.new("rubygems-update",
-                :require => Package["rubygems1.8"],
+              manifest[manager] << Puppet::Package.new("rubygems-update",
+                :require => Puppet::Package["rubygems1.8"],
                 :provider => :gem,
                 :ensure => :latest
               )
-              Package["rubygems1.8"]
+              Puppet::Package["rubygems1.8"]
             else
-              manifest[manager] << Exec.new(
+              manifest[manager] << Puppet::Exec.new(
                 "/usr/bin/gem#{v} install --no-rdoc --no-ri rubygems-update",
                 :alias => "rubygems-update-#{v}",
-                :require => Package["rubygems#{v}"]
+                :require => Puppet::Package["rubygems#{v}"]
               )
-              Exec["rubygems-update-#{v}"]
+              Puppet::Exec["rubygems-update-#{v}"]
             end
-            manifest[manager] << Exec.new(
+            manifest[manager] << Puppet::Exec.new(
               "/usr/bin/ruby#{v} /usr/bin/update_rubygems",
               :path => %W(/usr/bin /var/lib/gems/#{v}/bin),
               :require => prereq
             )
           end
 
-        # Only 1.8 can use the native gem package provider.
+        # RubyGems 1.8 is supported well enough by Puppet to include a
+        # native provider, which means it is almost as simple as `apt`.
         when "rubygems1.8"
           options = {
             :require => [
               Puppet::Class[managers[manager]],
-              Package["rubygems1.8"],
+              Puppet::Package["rubygems1.8"],
             ],
             :provider => :gem,
             :ensure => version
           }
-          manifest[manager] << Package.new(package, options)
+          manifest[manager] << Puppet::Package.new(package, options)
 
-        # Other gems use exec resources.
+        # Other RubyGems versions use `exec` resources for installation
+        # but follow a predictable enough directory layout that we can
+        # avoid running the `gem` command after the first run with an
+        # inexpensive check to see if the directory exists.
         when /rubygems/
-          manifest[manager] << Exec.new(
-            sprintf("#{command}", package, version),
+          manifest[manager] << Puppet::Exec.new(
+            sprintf(command, package, version),
             :creates =>
               "/usr/lib/ruby/gems/#{ruby_version}/gems/#{package}-#{version}",
             :require => [
               Puppet::Class[managers[manager]],
-              Package[manager],
+              Puppet::Package[manager],
             ]
           )
 
+        # Python packages follow a far less predictable directory naming
+        # scheme so we aren't able to optimize them like RubyGems.  They
+        # use `exec` resources and leave it to the Python tools (probably
+        # `easy_install`).
         when /python/
-          manifest[manager] << Exec.new(sprintf("#{command}", package),
+          manifest[manager] << Puppet::Exec.new(sprintf(command, package),
             :require => [
               Puppet::Class[managers[manager]],
-              Package[manager, "python-setuptools"],
+              Puppet::Package[manager, "python-setuptools"],
             ]
           )
 
-        # TODO Expand Java, Erlang, etc.
+        # It would be at this point where we would tackle Java, Erlang,
+        # and every other possible package manager.  Slow and steady.
 
+        # As a last resort, we execute the command exactly as the shell
+        # code generator would.
         else
-          manifest[manager] << Exec.new(sprintf("#{command}", package,
+          manifest[manager] << Puppet::Exec.new(sprintf(command, package,
             version), :require => [
               Puppet::Class[managers[manager]],
-              Package[manager],
+              Puppet::Package[manager],
             ]
           )
         end
       }
     )
 
-    # System files.
+    # System files must be placed after packages are installed so we set
+    # Puppet's dependencies to put all packages ahead of all files.
+    #
+    # File content is handled much like the shell version except base 64
+    # decoding takes place here in Ruby rather than in the `base64`(1)
+    # tool.  Resources for all parent directories are created ahead of
+    # any file.  Puppet's autorequire mechanism will ensure that a file's
+    # parent directories are realized before the file itself.
     if files && 0 < files.length
-      manifest << Package.defaults(
+      manifest << Puppet::Package.defaults(
         :before => files.sort.map { |pathname, content|
           Puppet::File[pathname]
         }
       )
       files.sort.each do |pathname, content|
+        dirnames = File.dirname(pathname).split("/")
+        dirnames.shift
+        (0..(dirnames.length - 1)).each do |i|
+          manifest << Puppet::File.new("/#{dirnames[0..i].join("/")}",
+            :ensure => :directory)
+        end
         if Hash == content.class
           if content["_target"]
             manifest << Puppet::File.new(pathname,
@@ -276,18 +379,23 @@ EOF
         end
         manifest << Puppet::File.new(pathname,
           :content => content,
-          :ensure => :present
+          :ensure => :file
         )
       end
     end
 
-    # Source tarballs.
+    # Source tarballs are downloaded, extracted, and removed in one fell
+    # swoop.  Puppet 2.6 introduced the requirement to wrap compound commands
+    # such as this in a shell invocation.  This is a pretty direct Puppet
+    # equivalent to the shell version above.
     if sources && 0 < sources.length
-      manifest << Package.defaults(
-        :before => sources.sort.map { |dirname, filename| Exec[pathname] }
+      manifest << Puppet::Package.defaults(
+        :before => sources.sort.map { |dirname, filename|
+          Puppet::Exec[pathname]
+        }
       )
       sources.sort.each do |dirname, filename|
-        manifest << Exec.new(filename,
+        manifest << Puppet::Exec.new(filename,
           :command => "/bin/sh -c 'wget http://s3.amazonaws.com/blueprint-sources/#{filename}; tar xf #{filename}; rm #{filename}'",
           :cwd => dirname
         )
@@ -297,57 +405,153 @@ EOF
     puts manifest
   end
 
-  def chef
-    puts "# No soup for you."
-    raise NotImplementedError, "Contractor::Blueprint#chef", caller
+  # This is the Chef code generator.  It is the first of its kind in
+  # creating a tarball rather than a single plaintext file.  Because of
+  # this added output complexity, an `IO`-like object is accepted and
+  # returned after being used by the underlying `Chef::Cookbook`.
+  def chef(io=StringIO.new)
+    cookbook = Chef::Cookbook.new(@name, disclaimer)
+
+    # First come packages, traversed in the same order as with the shell
+    # code generator but passed off to the cookbook.
+    walk(
+      :before => lambda { |manager, command|
+        cookbook.execute "apt-get update" if "apt" == manager
+      },
+      :package => lambda { |manager, command, package, version|
+        return if manager == package
+        command =~ /gem(\d+\.\d+(?:\.\d+)?) install/
+        ruby_version = $1
+        case manager
+
+        # `apt` packages use the builtin `package` resource type with the
+        # standard added resources to handle upgrading an old RubyGems
+        # install.
+        when "apt"
+          cookbook.apt_package package, :version => version
+          if package =~ /^rubygems(\d+\.\d+(?:\.\d+)?)$/
+            v = $1
+            cookbook.gem_package "rubygems-update",
+              :gem_binary => "/usr/bin/gem#{v}"
+            cookbook.execute "/bin/sh -c '/usr/bin/ruby#{v
+              } $(PATH=\"$PATH:/var/lib/gems/#{v
+              }/bin\" which update_rubygems)'"
+          end
+
+        # Gems themselves, no matter what version of Ruby they're for,
+        # can be managed by the builtin `package` resource type because
+        # Opscode thoughtfully allows specifying the `gem` command
+        # to run for each resource individually.
+        when /rubygems(\d+\.\d+(?:\.\d+)?)/
+          v = $1
+          cookbook.gem_package package,
+            :gem_binary => "/usr/bin/gem#{v}",
+            :version => version
+
+        # Because dependencies are handled by order, not declaration,
+        # Python packages that need to come after `python-setuptools`
+        # just do because `apt` is traversed first.  Everything else
+        # gets an `execute` resource here, too..
+        else
+          cookbook.execute sprintf(command, package, version)
+
+        end
+      }
+    )
+
+    # Files are handled by the `cookbook_file` resource type and are
+    # preceded by the `directory` which contains them.  Just like the
+    # shell and Puppet generators, this code handles binary files and
+    # symbolic links (handled by the `link` resource type), too.
+    files.sort.each do |pathname, content|
+      cookbook.directory File.dirname(pathname),
+        :group => "root",
+        :mode => "755",
+        :owner => "root",
+        :recursive => true
+      if Hash == content.class
+        if content["_target"]
+          cookbook.link pathname,
+            :group => "root",
+            :owner => "root",
+            :to => content["_target"]
+          next
+        elsif content["_base64"]
+          content = content["_base64"]
+        end
+      end
+      cookbook.cookbook_file pathname, content,
+        :backup => false,
+        :group => "root",
+        :mode => "644",
+        :owner => "root",
+        :source => pathname[1..-1]
+    end if files
+
+    # Source tarballs are lifted directly from the shell code generator
+    # and wrapped in `execute` resources.
+    sources.sort.each do |dirname, filename|
+      cookbook.execute \
+        "wget http://s3.amazonaws.com/blueprint-sources/#{filename}"
+      cookbook.execute "tar xf #{filename} -C #{dirname}"
+      cookbook.execute "rm #{filename}"
+    end if sources
+
+    # With the list of resources specified, generate a tarball.  The
+    # tarball will contain a minimal `metadata.rb`, a recipe, and any
+    # files that should be included.  The tarball is written to the
+    # `IO` object passed to this method.
+    puts cookbook.to_gz(io)
+
   end
 
   # Walk a package tree and execute callbacks along the way.  Callbacks
   # are listed in the options hash.  These are supported:
-  #   :before => lambda { |manager, command| }
-  #     Executed before a manager's dependencies are enumerated.
-  #   :package => lambda { |manager, command, package, version| }
-  #     Executed when a package is enumerated.
-  #   :after => lambda { |manager, command| }
-  #     Executed after a manager's dependencies are enumerated.
+  #
+  # * `:before => lambda { |manager, command| }`:
+  #   Executed before a manager's dependencies are enumerated.
+  # * `:package => lambda { |manager, command, package, version| }`:
+  #   Executed when a package is enumerated.
+  # * `:after => lambda { |manager, command| }`:
+  #   Executed after a manager's dependencies are enumerated.
   def walk(options={})
 
-    # Start with packages installed with apt.
+    # Start with packages installed with `apt`.
     options[:manager] ||= "apt"
 
-    # Handle managers.
+    # Each manager gets its chance to take action before we loop over all
+    # its managed packages.
     if options[:before].respond_to?(:call)
       options[:before].call options[:manager],
         packages[options[:manager]]["_command"]
     end
 
-    # Callback for each package that depends on this manager.  Note which
-    # ones themselves are managers.
+    # Each package gets its chance to take action.  While we're looping
+    # over all the packages, we must note which ones are themselves
+    # managers so we can recurse later.  We don't start the recursion
+    # now because of the possibility that packages managed by this
+    # just-encountered manager may also depend indirectly on packages
+    # yet to be installed at this level.
     managers = []
     packages[options[:manager]]["_packages"].sort.each do |package, version|
-
-      # Handle packages.
       if options[:package].respond_to?(:call)
         [version].flatten.each do |v|
           options[:package].call options[:manager],
             packages[options[:manager]]["_command"], package, v
         end
       end
-
       if options[:manager] != package && packages[package]
         managers << package
       end
     end
 
-    # Handle managers.
+    # Once more, each manager gets its chance to take action.
     if options[:after].respond_to?(:call)
       options[:after].call options[:manager],
         packages[options[:manager]]["_command"]
     end
 
-    # Recurse into each manager that was just installed.  This is done
-    # after the completed round because there could have been other
-    # dependencies at that level aside from the manager.
+    # Now we can recurse into each manager that was just installed.
     managers.each do |manager|
       walk options.merge(:manager => manager)
     end

data/lib/devstructure/chef.rb

@@ -0,0 +1,166 @@
+# The Chef code generator is structured much like the shell code generator
+# because Chef doesn't include any sort of dependency management like
+# Puppet.  As expected, we'll start with packages, follow them with files,
+# and finish with source tarballs.
+#
+# The monkeywrench is that the ultimate output is a tarball of a Chef
+# cookbook rather than a single file.  For this, we use the lower-level
+# APIs exposed by the `archive-tar-minitar` gem to generate tarballs
+# without writing intermediate files to disk.
+require 'devstructure'
+
+# Unfortunately, RubyGems rears its ugly head.  The call to `gem` here is
+# just because the gem's name is different than the path being `require`d.
+gem 'archive-tar-minitar', :require => 'archive/tar/minitar'
+require 'archive/tar/minitar'
+
+require 'zlib'
+
+module Chef
+
+  # A cookbook is a collection of Chef resources plus the files and other
+  # supporting objects needed to run it.
+  class Cookbook
+
+    # The name and options given to a cookbook become the filename and the
+    # parameters set in `metadata.rb`.  The comment is a bit awkward and
+    # exists so the disclaimer supplied with all blueprints can be shown
+    # at the top of `metadata.rb`.
+    def initialize(name, comment, options={})
+      @name, @comment, @options = name, comment, options
+      @resources, @files = [], {}
+    end
+
+    # Resources should be added in the order they're required to run.  That
+    # is how Chef manages dependencies.
+    def <<(resource)
+      @resources << resource
+    end
+
+    # In Chef, there are lots of top-level helpers for creating resources.
+    # This selection of almost-API-alikes facilitates the same thing for
+    # a `DevStructure::Chef::Cookbook`.
+    def apt_package(name, options={})
+      self << Chef::Resource.new(:apt_package, name, options)
+    end
+    def gem_package(name, options={})
+      self << Chef::Resource.new(:gem_package, name, options)
+    end
+    def execute(name, options={})
+      self << Chef::Resource.new(:execute, name, options)
+    end
+    def directory(name, options={})
+      self << Chef::Resource.new(:directory, name, options)
+    end
+    def link(name, options={})
+      self << Chef::Resource.new(:link, name, options)
+    end
+    def cookbook_file(name, content, options={})
+      self << Chef::Resource.new(:cookbook_file, name, options)
+      @files[name] = content
+    end
+
+    # This is where the magic happens.  The generated Chef cookbook will
+    # come as a tarball, written into whatever `IO`-like object is passed
+    # here.  The DevStructure website will pass `StringIO` while the
+    # command-line tools will pass `File`.
+    def to_gz(io)
+      mtime = Time.now
+      gz = Zlib::GzipWriter.new(io)
+      tar = Archive::Tar::Minitar::Writer.new(gz)
+      tar.mkdir @name, :mode => 0755, :mtime => mtime
+
+      # `metadata.rb` contains the typical DevStructure comment, a
+      # declaration of support for Ubuntu 10.04 or better, and any other
+      # metadata passed to the constructor of this `Cookbook`.
+      @options[:supports] ||= ["ubuntu", ">= 10.04"]
+      metadata = ([@comment] + @options.sort.collect do |key, value|
+        "#{key} #{[value].flatten.collect { |v| v.inspect }.join(", ")}\n"
+      end).join("")
+      tar.add_file_simple("#{@name}/metadata.rb", {
+        :mode => 0644,
+        :size => metadata.length,
+        :mtime => mtime
+      }) { |w| w.write metadata }
+
+      # Build the recipe.  Each resource handles its own stringification so
+      # the work done here amounts to gathering up a string and placing it
+      # in a file in the tarball.
+      resources = @resources.collect { |resource| resource.to_s }.join("")
+      tar.mkdir "#{@name}/recipes", :mode => 0755, :mtime => mtime
+      tar.add_file_simple("#{@name}/recipes/default.rb", {
+        :mode => 0644,
+        :size => resources.length,
+        :mtime => mtime
+      }) { |w| w.write resources }
+
+      # Included any files referenced by `cookbook_file` resources.  They
+      # all appear in `files/default/` as if that is the root of the
+      # filesystem.
+      if 0 < @files.length
+        tar.mkdir "#{@name}/files", :mode => 0755, :mtime => mtime
+        tar.mkdir "#{@name}/files/default", :mode => 0755, :mtime => mtime
+        @files.each do |name, content|
+          dirnames = File.dirname(name).split("/")
+          dirnames.shift
+          (0..(dirnames.length - 1)).each do |i|
+            tar.mkdir "#{@name}/files/default/#{dirnames[0..i].join("/")}",
+              :mode => 0755, :mtime => mtime
+          end
+          tar.add_file_simple("#{@name}/files/default#{name}", {
+            :mode => 0644,
+            :size => content.length,
+            :mtime => mtime
+          }) { |w| w.write content }
+        end
+      end
+
+      # Return the finalized tarball.
+      tar.close
+      gz.close
+      io
+
+    end
+
+  end
+
+  # This is a generic Chef resource.  One would be wise to use the helpers
+  # available in the `Cookbook` class.
+  class Resource < Hash
+
+    # A Chef resource has a type, a name, and some options.  The type is
+    # simply the name of the method that will be called in the recipe file.
+    # the name is the only argument to that method.  The options will be
+    # converted to method calls and arguments within the block attached to
+    # each resource.
+    def initialize(type, name, options={})
+      super nil
+      clear
+      options.each { |k, v| self[k.to_s] = v }
+      @type, @name = type, name
+    end
+
+    # Stringify differently depending on the number of options so the
+    # output always looks like Ruby code should look.  Parentheses are
+    # always employed here due to grammatical inconsistencies when using
+    # braces surrounding a block.
+    def to_s
+      case length
+      when 0
+        "#{@type}(#{@name.inspect})\n"
+      when 1
+        key, value = dup.shift
+        "#{@type}(#{@name.inspect}) { #{key} #{value.inspect} }\n"
+      else
+        out = ["#{@type}(#{@name.inspect}) do\n"]
+        out += sort.collect do |key, value|
+          "\t#{key} #{value.inspect}\n"
+        end
+        out << "end\n"
+        out.join("")
+      end
+    end
+
+  end
+
+end

data/lib/devstructure/puppet.rb

@@ -1,6 +1,21 @@
+# The Puppet code generator is used by
+# [`blueprint-create`(1)][blueprint-create] and
+# [`blueprint-show`(1)][blueprint-show].  It operates on the
+# [`blueprint`(5)][blueprint] JSON format generated by
+# [`sandbox-blueprint`(1)][sandbox-blueprint].
+#
+# A manifest contains a collection of zero or more child manifests,
+# which are eventually namespaced beneath their parent, and zero or
+# more child resources, which are listed in no particular order.
+#
+# [blueprint-create]: http://devstructure.github.com/contractor/blueprint-create.1.html
+# [blueprint-show]: http://devstructure.github.com/contractor/blueprint-show.1.html
+# [blueprint]: http://devstructure.github.com/contractor/blueprint.5.html
+# [sandbox-blueprint]: http://devstructure.github.com/contractor/sandbox-blueprint.1.html
 require 'devstructure'
 
-# Make symbols Comparable.
+# Make `Symbol`s `Comparable` so we can sort each list of resource
+# attributes before converting to a string.
 class Symbol
   def <=>(other)
     to_s <=> other.to_s
@@ -10,15 +25,21 @@ end
 module DevStructure::Puppet
 
   # A Puppet manifest that contains a tree of classes that each contain
-  # some resources.
+  # some resources.  Manifests are valid targets of dependencies and we
+  # use them heavily in the generated code to keep the inhumane-ness to
+  # a minimum.  A Manifest object generates a Puppet `class`.
   class Manifest
 
+    # Each class must have a name and might have a parent.  If a manifest
+    # has a parent, this signals it to `include` itself in the parent.
     def initialize(name, parent=nil)
       @name, @parent = name, parent
       @manifests, @resources = {}, {}
     end
 
-    # Return a reference to a sub-manifest of the given name.
+    # Manifests behave a bit like hashes in that their children can be
+    # traversed.  Note the children can't be assigned directly because
+    # we must maintain parent-child relationships.
     def [](name)
       @manifests[name.to_s] ||= self.class.new(name.to_s, @name)
     end
@@ -26,28 +47,36 @@ module DevStructure::Puppet
       self[symbol]
     end
 
-    # Add a resource to this manifest.
+    # Add a resource to this manifest.  Order is never important in Puppet
+    # since all dependencies must be declared.
     def <<(resource)
-      @resources[resource.type] ||= []
-      @resources[resource.type] << resource
+      @resources[resource.type] ||= {}
+      @resources[resource.type][resource.name] = resource
     end
 
+    # Turn this manifest into a Puppet class.  We start with a base level
+    # of indentation that we carry through our resources and manifests.
+    # Order is again not important so we don't make much effort.  The
+    # Puppet grammar prohibits dots in class names so we replace `.` with
+    # `--`.  Resources are grouped by type to reduce the total number of
+    # lines required.  If this manifest has a parent, the last thing we
+    # do is include ourselves in the parent.
     def to_s(tab="")
       out = []
       out << "#{tab}class #{@name.gsub(".", "--")} {"
       @manifests.each_value do |manifest|
         out << manifest.to_s("#{tab}\t")
       end
-      @resources.each do |type, resources|
+      @resources.sort.each do |type, resources|
         if 1 < resources.length
           out << "#{tab}\t#{type} {"
-          resources.each do |resource|
+          resources.sort.each do |name, resource|
             resource.style = :partial
             out << resource.to_s("#{tab}\t")
           end
           out << "#{tab}\t}"
         else
-          out << resources.first.to_s("#{tab}\t")
+          out << resources.values.first.to_s("#{tab}\t")
         end
       end
       out << "#{tab}}"
@@ -57,13 +86,15 @@ module DevStructure::Puppet
 
   end
 
-  # A generic Puppet resource to be subclassed.  The name of the class
-  # dictates how the resource will be printed so do not instantiate this
-  # class directly.
+  # A Puppet resource is basically a named hash.  The name is unique
+  # the Puppet catalog (which may contain any number of manifests in
+  # any number of modules).  The attributes that are expected vary
+  # by the resource's actual type.  This implementation uses the class
+  # name to determine the type, so do not instantiate `Resource`
+  # directly.
   class Resource < Hash
     attr_accessor :type, :name, :style
 
-    # A resource.
     def initialize(name, options={})
       super nil
       clear
@@ -73,9 +104,10 @@ module DevStructure::Puppet
       @style = :complete
     end
 
-    # A resource with only a name, typically being listed as a dependency.
-    # This method enables syntax that looks a lot like the Puppet code that
-    # will be generated.
+    # Resources that are just being listed as dependencies don't need to
+    # have all their attributes.  This method exists as syntactic sugar
+    # for declaring dependencies because it results in something that
+    # looks quite a bit like the Puppet language's resource references.
     def self.[](*args)
       if 1 == args.length
         self.new args[0]
@@ -84,7 +116,9 @@ module DevStructure::Puppet
       end
     end
 
-    # A set of defaults for a resource type.
+    # In the Puppet language, a capitalized resource type can be used to
+    # provide default values for a type.  `DevStructure::Blueprint` sets
+    # defaults to provide some inherent order to the Puppet run.
     def self.defaults(options)
       resource = self.new(nil, options)
       resource.style = :defaults
@@ -93,7 +127,7 @@ module DevStructure::Puppet
 
     # Return Puppet code for this resource.  Whether a complete, partial,
     # or defaults representation is returned depends on which class method
-    # instantiated this resource but can be overridden by passing a Symbol.
+    # instantiated this resource but can be overridden by passing a `Symbol`.
     def to_s(tab="")
       out = []
 
@@ -113,16 +147,19 @@ module DevStructure::Puppet
         raise ArgumentError
       end
 
-      # Handle the options Hash.
+      # Handle a non-empty set of attributes in alphabetical order and
+      # in compliance with the Puppet coding standards.  This is a bit
+      # conservative and so uses more vertical space than absolutely
+      # necessary but it also won't get obnoxiously long.
       if 0 < length
 
-        # Note the longest option name so we can line up => operators as
+        # Note the longest option name so we can line up `=>` operators as
         # per the Puppet coding standards.
         l = collect { |k, v| k.to_s.length }.max
 
-        # Map options to Puppet code strings.  Symbols become unquoted
-        # strings, nils become undefs, and Arrays are flattened.  Unless
-        # the value is a Symbol, #inspect is called on the value.
+        # Map options to Puppet code strings.  `Symbol`s become unquoted
+        # strings, `nil`s become `undef`s, and arrays are flattened.
+        # Unless the value is a `Symbol`, #inspect is called on the value.
         out += sort.collect do |k, v|
           k = "#{k.to_s}#{" " * (l - k.to_s.length)}"
           v = if v.respond_to?(:flatten)
@@ -139,7 +176,7 @@ module DevStructure::Puppet
           "\t#{tab_params}#{k} => #{v},"
         end
 
-        # Close this resource.
+        # Close this resource to match the opening.
         case @style
         when :complete
           out << "#{tab}}"
@@ -149,8 +186,8 @@ module DevStructure::Puppet
           out << "#{tab}}"
         end
 
-      # Don't bother with an empty options Hash.  Go ahead and close this
-      # resource.
+      # Don't bother with an empty options hash.  Go ahead and close this
+      # resource as inconspicuously as possible.
       else
         case @style
         when :complete
@@ -165,8 +202,8 @@ module DevStructure::Puppet
       out.join "\n"
     end
 
-    # Resources themselves appear in options as dependencies so they are
-    # represented in Puppet's reference notation.
+    # Resources themselves can appear in attributes as dependencies.  Their
+    # inspected value matches the Puppet resource reference syntax.
     def inspect
       "#{@type.capitalize}[\"#{@name}\"]"
     end
@@ -176,15 +213,16 @@ module DevStructure::Puppet
 
   end
 
-  # Some actual resource types.
-  class Package < Resource
-  end
-  class Exec < Resource
-  end
-  class File < Resource
-  end
+  # As mentioned earlier, we use the class name to determine the resource
+  # type.  The most common types are `Package`, `Exec`, and `File`.
+  class Package < Resource; end
+  class Exec < Resource; end
+  class File < Resource; end
 
-  # A class resource type for dependencies.
+  # `Class` is also a useful resource type but needs a little more help
+  # because of the stricter rules governing class names in the Puppet
+  # grammar.  The most common problem is a dot in a package name (like
+  # `ruby1.8`, which we replace with `--` in the generated code).
   class Class < Resource
     def inspect
       "#{@type.capitalize}[\"#{@name.gsub(".", "--")}\"]"

data/lib/devstructure.rb

@@ -1,2 +1,20 @@
+# The Ruby bindings to the DevStructure API actually include a bit more
+# than that.  The following independent modules are available - this
+# serves as nothing more than the root of a namespace.
+#
+# * [`DevStructure::API`](devstructure/api.html):
+#   The actual API client as a subclass of `Net::HTTP`.
+# * [`DevStructure::Blueprint`](devstructure/blueprint.html):
+#   A Ruby class describing a blueprint.
+# * [`DevStructure::Puppet`](devstructure/puppet.html):
+#   A Puppet code generator.
+# * [`DevStructure::Chef`](devstructure/chef.html):
+#   A Chef code generator.
+#
+# Further reading:
+#
+# * [DevStructure API documentation](http://docs.devstructure.com/api)
+# * [`ruby-devstructure`(7)](ruby-devstructure.7.html)
+# * [Source code](http://github.com/devstructure/ruby-devstructure)
 module DevStructure
 end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: devstructure
 version: !ruby/object:Gem::Version 
-  hash: 11
+  hash: 23
   prerelease: false
   segments: 
   - 0
-  - 1
-  - 8
-  version: 0.1.8
+  - 2
+  - 0
+  version: 0.2.0
 platform: ruby
 authors: 
 - Richard Crowley
@@ -15,7 +15,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-08-06 00:00:00 +00:00
+date: 2010-08-24 00:00:00 +00:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -34,6 +34,34 @@ dependencies:
         version: 1.4.2
   type: :runtime
   version_requirements: *id001
+- !ruby/object:Gem::Dependency 
+  name: ronn
+  prerelease: false
+  requirement: &id002 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
+        version: "0"
+  type: :development
+  version_requirements: *id002
+- !ruby/object:Gem::Dependency 
+  name: rocco
+  prerelease: false
+  requirement: &id003 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
+        version: "0"
+  type: :development
+  version_requirements: *id003
 description: Ruby bindings to the DevStructure API
 email: richard@devstructure.com
 executables: []
@@ -47,6 +75,7 @@ files:
 - lib/devstructure/api.rb
 - lib/devstructure/blueprint.rb
 - lib/devstructure/puppet.rb
+- lib/devstructure/chef.rb
 has_rdoc: true
 homepage: http://github.com/devstructure/ruby-devstructure
 licenses: []