puppet-module 0.3.0

data/CHANGES.markdown

@@ -0,0 +1,91 @@
+puppet-module changes
+=====================
+
+r0.3.0
+------
+
+* Renamed CLI tool and gem to `puppet-module`. Please run `gem uninstall pmt` to get rid of old versions of the program.
+* Added 'usage' action to display the usage information for this tool.
+* Added 'changelog' action to display the changelog for this tool.
+
+r0.2.9
+------
+
+* Fixed 'generate' action to create files and directories that follow Puppet best-practices.
+
+r0.2.8
+------
+
+* Fixed rake tasks so that RSpec isn't required to run those tasks that don't need it.
+* Fixed generated dependency metadata so that version and repository values are only set if specified.
+
+r0.2.7
+------
+
+* Fixed program so it'd be pure Ruby, it used to depend on the Versionomy library which required compiled extensions.
+
+r0.2.6
+------
+
+* Fixed gem builder to no longer install Puppet as a dependency since users can have a non-gem version.
+
+r0.2.5
+------
+
+* Added ability to specify username and password credentials for a repository URL, e.g.: http://myuser:mypassword@myrepository.com/
+
+r0.2.4
+------
+
+* Improved user documentation, explained different ways to run the program.
+
+r0.2.3
+------
+
+* Fixed Rakefile, readded the rspec tasks inadvertantly removed in r0.2.2.
+* Fixed builder to extract information about Puppet providers.
+* Fixed tool's method for getting the current repository to use Puppet's settings.
+* Improved cli_spec, added examples describing how to build a module's checksums, dependencies and Puppet types and providers.
+* Improved builder to produce pretty JSON that's easy for a human to read.
+
+r0.2.2
+------
+
+* Fixed unpacker to use the private working directory instead of '/tmp'.
+* Fixed installer, it now detects if a module is already installed.
+* Fixed default repository path to 'http://forge.puppetlabs.com'
+* Fixed README's license text to explain that GPLv2 or later is acceptable.
+* Added `rake gem` to build a gem in the 'pkg' directory.
+
+r0.2.1
+------
+
+* Fixed license to refer to 'Puppet Labs'.
+* Added user documentation to `README.markdown`.
+
+r0.2.0
+------
+
+* Fixed errors causing tool to add unwanted hyphens to ends of names.
+* Fixed loading of 'puppet' gem conditionally, instead of failing on startup.
+* Fixed startup to create required work directory, instead of failing on startup.
+* Fixed repository to use a default repository URL rather than failing without arguments.
+* Fixed setting of module's full name to ensure a valid name.
+* Fixed generator to refuse to generate a directory with an invalid name.
+* Fixed installer to refuse to install a file with an invalid name.
+* Fixed unpacker to install into directory with the module's full name.
+* Fixed installer to install files from the local filesystem.
+* Fixed lookup of tool's root directory to use correct, simple and reliable mechanism.
+* Fixed problematic 'autoload' calls and reorganized how libraries are loaded.
+* Fixed and expanded README instructions.
+* Disabled actions 'freeze', 'register', 'release' and 'unrelease' to save time, users can use the website for these.
+* Improved cleaner, it can now be called as a library method.
+* Added test suite, brought test code coverage up to 86%.
+* Added documentation to most of application's methods, classes, and lightly refactored.
+* Added libraries and methods to stub and test methods accessing remote resources.
+* Added #tap and #returning methods to clarify code.
+
+r0.1.0
+------
+
+Initial draft.

data/LICENSE

@@ -0,0 +1,17 @@
+Copyright (C) 2010 Puppet Labs Inc.
+
+Puppet Labs can be contacted at: info@puppetlabs.com
+
+This program and entire repository is free software; you can
+redistribute it and/or modify it under the terms of the GNU
+General Public License as published by the Free Software
+Foundation; either version 2 of the License, or any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+GNU General Public License for more details.
+
+You should have received a copy of the GNU General Public License
+along with this program; if not, write to the Free Software
+Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA

data/README.markdown

@@ -0,0 +1,221 @@
+Puppet Module Tool
+==================
+
+The Puppet Module Tool, `puppet-module`, creates, installs and searches for
+modules on the Puppet Forge at http://forge.puppetlabs.com
+
+Dependencies
+------------
+
+To run `puppet-module`, you must have the following installed:
+
+* Ruby 1.8.x: http://www.ruby-lang.org/en/downloads/
+* RubyGems 1.3.x: http://rubygems.org/pages/download/
+* Puppet 0.25.x: http://www.puppetlabs.com/
+
+Soure code
+----------
+
+The source code for this tool is available online at
+http://github.com/puppetlabs/puppet-module-tool
+
+You can checkout the source code by installing the `git` distributed version
+control system and running:
+
+    git clone git://github.com/puppetlabs/puppet-module-tool.git
+
+Running
+-------
+
+There are a number of ways to run the `puppet-module` program:
+
+1. *From a source code checkout:* Checkout the source code and from the checkout
+directory, run:
+
+    alias puppet-module=$PWD/bin/puppet-module
+
+2. *From a locally-built gem:* Checkout the source code and from the checkout
+directory, run:
+
+    # Build the gem
+    rake gem
+    # Install the file produced by the above command, e.g.:
+    sudo gem install pkg/puppet-module-0.3.0.gem
+
+3. *From an official gem:* Install it by running:
+
+    sudo gem install puppet-module
+
+Basics
+------
+
+Display the program's built-in help by running:
+
+    puppet-module help
+
+Display information on a specific command by running a command like:
+
+    puppet-module help install
+
+Many commands will use a specific repository if you pass it to the `-r`
+option at the end, like:
+
+    puppet-module search mymodule -r http://forge.puppetlabs.com/
+
+Search for modules
+------------------
+
+Searching displays modules on the repository that match your query.
+
+For example, search the default repository for modules whose names
+include the substring `mymodule`:
+
+    puppet-module search mymodule
+
+Install a module release
+------------------------
+
+Installing a module release from a repository downloads a special
+archive file. This archive is then automatically unpacked into a new
+directory under your current directory. You can then add this *module
+directory* to your Puppet configuration files to use it.
+
+For example, install the latest release of the module named `mymodule`
+written by `myuser` from the default repository:
+
+    puppet-module install myuser-mymodule
+
+Or install a specific version:
+
+    puppet-module install myuser-mymodule --version=0.0.1
+
+Generate a module
+-----------------
+
+Generating a new module produces a new directory prepopulated with a
+directory structure and files recommended for Puppet best practices.
+
+For example, generate a new module:
+
+    puppet-module generate myuser-mymodule
+
+The above command will create a new *module directory* called
+`myuser-mymodule` under your current directory with the generated files.
+
+Please read the files in this generated directory for further details.
+
+Build a module release
+----------------------
+
+Building a module release processes the files in your module directory
+and produces a special archive file that you can share or install.
+
+For example, build a module release from within the module directory:
+
+    puppet-module build
+
+The above command will report where it created the module release
+archive file.
+
+For example, if this was version `0.0.1` of `myuser-mymodule`, then this
+would have created a `pkg/myuser-mymodule-0.0.1.tar.gz` release file.
+
+The build process reads a `Modulefile` in your module directory and uses
+its contents to direct its work.
+
+The `Modulefile` is a *Ruby domain-specific language (DSL)*.
+
+Here's an example of a `Modulefile`:
+
+    name 'myuser-mymodule'
+    version '0.0.1'
+    dependency 'otheruser-othermodule', '1.2.3'
+
+The build process reads the `Modulefile` and uses it to build a
+`metadata.json` file. This generated JSON file is included in the module
+release archive so that repositories and installers can extract details
+from your release. Do **not** edit this `metadata.json` file yourself
+because it's clobbered each time during the build process -- you should
+make all your changes to the `Modulefile` instead.
+
+All the files in the `pkg` directory of your module directory are
+artifacts of the build process. You can delete them when you're done.
+
+Share a module
+--------------
+
+Sharing a module release with others helps others avoid reinventing the
+wheel, and encourages them to help with your work by improving it. For
+every module you share, we hope you'll find many modules by others that
+will be useful to you.
+
+You can share your modules at http://forge.puppetlabs.com/
+
+Building and sharing a new module version
+-----------------------------------------
+
+To build and share a new module version:
+
+1. Edit the `Modulefile` and increase the `version` number.
+2. Run the `puppet-module build` as explained in the *Build a module release* section.
+3. Upload the new release file as explained in the *Share a module* section.
+
+Cleaning the cache
+------------------
+
+Modules that you install are saved to a cache within your `~/.puppet`
+directory. This cache can be cleaned out by running:
+
+    puppet-module clean
+
+Deleting a module
+-----------------
+
+The tool does not keep track of what modules you have installed. TO delete a
+module just delete the directory the module was extracted into.
+
+Get involved
+------------
+
+This is new and exciting for us. We have many plans for this and what
+you see now is just the beginning. If you have ideas, please get in
+touch. Puppet Labs can be contacted at: info@puppetlabs.com
+
+Technical disclaimer for techies
+--------------------------------
+
+This tool downloads untrusted code from the Internet. Please read the
+source code before executing it to avoid surprises. If it breaks, it's
+not our fault -- although we encourage you to contact the authors,
+file a bug report and send patches.
+
+Legal disclaimer for lawyers
+----------------------------
+
+THE PROGRAM AND MODULES ARE DISTRIBUTED IN THE HOPE THAT THEY WILL BE
+USEFUL, BUT WITHOUT ANY WARRANTY. THEY ARE PROVIDED "AS IS" WITHOUT
+WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT
+LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
+PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF
+THE PROGRAM IS WITH YOU. SHOULD THE PROGRAM OR MODULES PROVE DEFECTIVE,
+YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION.
+
+IN NO EVENT WILL Puppet Labs Inc. BE LIABLE TO YOU FOR DAMAGES,
+INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES
+ARISING OUT OF THE USE OR INABILITY TO USE THIS PROGRAM OR MODULES
+(INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED
+INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF
+THE PROGRAM OR MODULES TO OPERATE WITH ANY OTHER PROGRAMS OR MODULES),
+EVEN IF Puppet Labs Inc. HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH
+DAMAGES.
+
+License
+-------
+
+This software is distributed under the GNU General Public License
+version 2 or any later version. See the LICENSE file for details.
+
+Copyright
+---------
+
+Copyright (C) 2010 Puppet Labs Inc.

data/Rakefile

@@ -0,0 +1,87 @@
+require 'rubygems'
+require 'rake'
+require 'rake/gempackagetask'
+require 'fileutils'
+require 'ftools'
+
+# Return filename matching an array of glob patterns, minus any ephemeral files
+# that don't belong in the gem.
+def sanitized_file_list(*args)
+  return FileList[*args].reject{|filename| filename =~ /\.(~|swp|tmp)\z/}
+end
+
+GEM_FILES = sanitized_file_list [
+    'CHANGES.markdown',
+    'LICENSE',
+    'README.markdown',
+    'Rakefile',
+    'VERSION',
+    'bin/**/*',
+    'lib/**/*',
+    'templates/**/*',
+    'vendor/**/*'
+]
+
+gemspec = Gem::Specification.new do |gemspec|
+    gemspec.name = 'puppet-module'
+    gemspec.files = GEM_FILES.to_a
+    gemspec.executables = ['puppet-module']
+    gemspec.version = File.read('VERSION')
+    gemspec.date = File.new('VERSION').mtime
+    gemspec.summary = 'The Puppet Module Tool manages Puppet modules'
+    gemspec.description = 'The Puppet Module Tool creates, installs and searches for Puppet modules.'
+    gemspec.author = 'Igal Koshevoy'
+    gemspec.email = 'igal@pragmaticraft.com'
+    gemspec.homepage = 'http://github.com/puppetlabs/puppet-module-tool'
+    gemspec.rdoc_options = ['--main', 'README.rdoc']
+    gemspec.require_paths = ['lib']
+    gemspec.test_files = sanitized_file_list ['spec/**/*']
+    gemspec.post_install_message = <<-POST_INSTALL_MESSAGE
+#{'*'*78}
+
+  Thank you for installing puppet-module from Puppet Labs!
+
+  * Usage instructions: read "README.markdown" or run `puppet-module usage`
+  * Changelog: read "CHANGES.markdown" or run `puppet-module changelog`
+  * Puppet Forge: visit http://forge.puppetlabs.com/
+
+#{'*'*78}
+    POST_INSTALL_MESSAGE
+end
+
+Rake::GemPackageTask.new(gemspec) do |pkg|
+    pkg.need_zip = true
+    pkg.need_tar = true
+end
+
+begin
+  require 'spec/rake/spectask'
+  Spec::Rake::SpecTask.new(:spec) do |spec|
+      spec.libs << 'lib' << 'spec'
+      spec.spec_files = ['spec/**/*_spec.rb']
+  end
+
+  Spec::Rake::SpecTask.new(:rcov) do |spec|
+      spec.libs << 'lib' << 'spec'
+      spec.pattern = 'spec/**/*_spec.rb'
+      spec.rcov = true
+  end
+rescue LoadError
+  task :spec do
+    puts 'ERROR! RSpec not found, install it by running: sudo gem install rspec'
+  end
+
+  task :rcov => :spec
+end
+
+task :default => :spec
+
+require 'rake/rdoctask'
+Rake::RDocTask.new do |rdoc|
+    version = File.read('VERSION')
+
+    rdoc.rdoc_dir = 'rdoc'
+    rdoc.title = "puppet-modules #{version}"
+    rdoc.rdoc_files.include('README*')
+    rdoc.rdoc_files.include('lib/**/*.rb')
+end

data/VERSION

@@ -0,0 +1 @@
+0.3.0

data/bin/puppet-module

@@ -0,0 +1,7 @@
+#!/usr/bin/env ruby
+
+$LOAD_PATH.unshift(File.dirname(__FILE__) + "/../lib")
+
+require 'puppet/module/tool'
+
+Puppet::Module::Tool::CLI.start

data/lib/puppet/module/tool.rb

@@ -0,0 +1,124 @@
+# Load standard libraries
+require 'pathname'
+require 'fileutils'
+
+# Define tool
+module Puppet
+  class Module
+    module Tool
+      # Default repository URL.
+      REPOSITORY_URL = 'http://forge.puppetlabs.com'
+
+      # Directory names that should not be checksummed.
+      ARTIFACTS = ['pkg', /^\./, /^~/, /^#/, 'coverage']
+
+      # Is this a directory that shouldn't be checksummed?
+      #
+      # TODO: Should this be part of Checksums?
+      # TODO: Rename this method to reflect it's purpose?
+      # TODO: Shouldn't this be used when building packages too?
+      def self.artifact?(path)
+        case File.basename(path)
+        when *ARTIFACTS
+          true
+        else
+          false
+        end
+      end
+
+      # Return Pathname for the directory this tool was installed into.
+      def self.root
+        @root ||= Pathname.new(File.expand_path(File.join(File.dirname(File.expand_path(__FILE__)), '..', '..', '..')))
+      end
+
+      # Return the tool's string version.
+      def self.version
+        @version ||= (root + 'VERSION').read
+      end
+
+      # Return Pathname for this tool's working directory.
+      def self.working_dir
+        @working_dir ||= Pathname.new(Puppet.settings[:puppet_module_working_dir])
+      end
+
+      # Return Repository to fetch data from based on Puppet's config file.
+      def self.repository
+        @repository ||= Repository.new(Puppet.settings[:puppet_module_repository])
+      end
+
+      FULL_NAME_PATTERN = /\A(.+)[\/\-](.+)\z/
+
+      # Return the +username+ and +modname+ for a given +full_name+, or raise an
+      # ArgumentError if the argument isn't parseable.
+      def self.username_and_modname_from(full_name)
+        if matcher = full_name.match(FULL_NAME_PATTERN)
+          return matcher.captures
+        else
+          raise ArgumentError, "Not a valid full name: #{full_name}"
+        end
+      end
+
+      # Return the filename with the usage documenation.
+      def self.usage_filename
+        return File.expand_path(File.join(self.root, 'README.markdown'))
+      end
+
+      # Return the filename with the changelog.
+      def self.changelog_filename
+        return File.expand_path(File.join(self.root, 'CHANGES.markdown'))
+      end
+    end
+  end
+end
+
+# Add vendored code paths to $LOAD_PATH
+Dir[Puppet::Module::Tool.root + 'vendor/*/lib'].each do |path|
+  $LOAD_PATH.unshift(path)
+end
+
+# Load vendored libraries
+require 'facets/kernel/tap'
+require 'facets/kernel/returning'
+
+# Load rubygems, so we can load Puppet and parse version numbers
+require 'rubygems'
+
+# Load Puppet
+begin
+  minimum_version = Gem::Version.new("0.25.0")
+  message = "You must have Puppet #{minimum_version} or greater installed"
+
+  begin
+    require 'puppet'
+  rescue LoadError
+    abort message
+  end
+
+  begin
+    current_version = Gem::Version.new(Puppet.version)
+  rescue
+    abort "#{message} -- couldn't parse version"
+  end
+
+  if current_version <= minimum_version
+    abort "#{message} -- you're running #{current_version}"
+  end
+end
+
+# Add support for Puppet's settings file
+require 'puppet/module/tool/utils'
+module Puppet::Module::Tool
+  extend Utils::Settings
+end
+
+# Load remaining libraries
+require 'puppet/module/tool/applications'
+require 'puppet/module/tool/cache'
+require 'puppet/module/tool/checksums'
+require 'puppet/module/tool/cli'
+require 'puppet/module/tool/contents_description'
+require 'puppet/module/tool/dependency'
+require 'puppet/module/tool/metadata'
+require 'puppet/module/tool/modulefile'
+require 'puppet/module/tool/repository'
+require 'puppet/module/tool/skeleton'