cartage 1.2 → 2.0.rc1

data/lib/cartage/backport.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+# :nocov:
+if Gem::Version.new(RUBY_VERSION) < Gem::Version.new('2.3')
+  # An implementation of #dig for Ruby pre-2.3. Based originally on
+  # {Invoca/ruby_dig}[https://github.com/Invoca/ruby_dig] with some inspiration
+  # from {jrochkind/dig_rb}[https://github.com/jrochkind/dig_rb].
+  module Cartage::Dig #:nodoc:
+    def dig(key, *rest)
+      value = self[key]
+
+      if value.nil? || rest.empty?
+        value
+      elsif value.respond_to?(:dig)
+        value.dig(*rest)
+      else
+        fail TypeError, "#{value.class} does not have #dig method"
+      end
+    end
+  end
+
+  ::Array.send(:include, Cartage::Dig) unless ::Array.public_method_defined?(:dig)
+  ::Hash.send(:include, Cartage::Dig) unless ::Hash.public_method_defined?(:dig)
+
+  unless ::Struct.public_method_defined?(:dig)
+    # Struct gets a different override.
+    module Cartage::StructDig # :nodoc:
+      include Cartage::Dig
+
+      # This override is necessary because <tt>Struct.new(:a).new(1)[0]</tt> is
+      # *legal*. So we don't just care about NameError, but IndexError as well.
+      def dig(name, *rest)
+        super
+      rescue IndexError, NameError
+        nil
+      end
+    end
+
+    ::Struct.send(:include, Cartage::StructDig)
+  end
+
+  unless ::OpenStruct.public_method_defined?(:dig)
+    # OpenStruct gets a different override.
+    module Cartage::OpenStructDig # :nodoc:
+      def dig(name, *rest)
+        @table.dig(name.to_sym, *rest)
+      rescue NoMethodError
+        raise TypeError, "#{name} is not a symbol nor a string"
+      end
+    end
+
+    ::OpenStruct.send(:include, Cartage::OpenStructDig)
+  end
+end
+
+unless Pathname.public_method_defined?(:write)
+  ##
+  module Cartage::PathnameWrite #:nodoc:
+    def write(*args)
+      IO.write(to_s, *args)
+    end
+  end
+
+  ::Pathname.send(:include, Cartage::PathnameWrite)
+end
+# :nocov:

data/lib/cartage/cli.rb

@@ -0,0 +1,234 @@
+# frozen_string_literal: true
+
+require 'cartage'
+require_relative 'gli_ext'
+
+::GLI::Commands::Help.skips_pre = false
+
+##
+class Cartage
+  # The Cartage command-line application, as a GLI application.
+  class CLI
+    # Commands that want to return a non-zero exit code without a displayed
+    # message should raise Cartage::QuietExit with the exit status.
+    class QuietExit < StandardError
+      include ::GLI::StandardException
+
+      def initialize(exit_code) #:nodoc:
+        @exit_code = exit_code
+      end
+
+      # The exit code to be used.
+      attr_reader :exit_code
+    end
+
+    # A local alias for GLI::CustomExit. Initialize with +message+ and
+    # +exit_status+. The message will be displayed, and the exit status will be
+    # returned. This should be used for *failure* of the command.
+    class CustomExit < ::GLI::CustomExit; end
+
+    # A local alias for GLI::CommandException. This exception is similar to
+    # CustomExit, but should be used when there is a configuration issue, or a
+    # conflict in flags or switches. It requires three parameters:
+    #
+    # 1. The message;
+    # 2. The command name for help (+command.name_for_help+);
+    # 3. The exit status.
+    class CommandException < ::GLI::CommandException; end
+
+    Cartage::Plugin.load
+
+    include ::GLI::App #:nodoc:
+
+    class << self
+      # When called with a block, this method reopens Cartage::CLI to add new
+      # commands. If modules are provided, the normal Object#extend method
+      # will be called.
+      #
+      # +mods+ are the modules to extend onto Cartage::CLI. +block+ is the
+      # block that contains CLI command extensions (using the GLI DSL).
+      def extend(*mods, &block)
+        super(*mods) unless mods.empty?
+        cli.instance_eval(&block) if block_given?
+      end
+
+      # Run the application. Should only be run from +bin/cartage+. +args+ are
+      # the command-line arguments (e.g., +ARGV+) to the CLI.
+      def run(*args)
+        cli.run(*args)
+      end
+
+      private
+
+      def cli
+        @cli ||= new
+      end
+
+      private :new
+    end
+
+    # The Cartage configuration and execution engine for the running instance
+    # of the Cartage CLI. The first time that this is used, an explicit
+    # +config+ (which must be a Cartage::Config object) may be provided.
+    def cartage(config = nil)
+      if defined?(@cartage) && @cartage && config
+        fail 'Cannot provide another configuration after initialization.'
+      end
+      @cartage ||= Cartage.new(config)
+    end
+
+    attr_writer :backtrace # :nodoc:
+
+    # Indicates whether backtrace printing is turned on.
+    def backtrace?
+      !!@backtrace
+    end
+  end
+
+  CLI.extend do
+    accept(Cartage::Config) do |value|
+      Cartage::Config.load(value)
+    end
+
+    program_desc 'Manage releaseable packages'
+    program_long_desc <<-'DESC'
+Cartage provides a repeatable means to create a package for a server-side
+application that can be used in deployment with a configuration tool like
+Ansible, Chef, Puppet, or Salt.
+    DESC
+    version Cartage::VERSION
+
+    subcommand_option_handling :normal
+    arguments :strict
+    synopsis_format :terminal
+
+    desc 'Silence normal output.'
+    switch %i(q quiet)
+
+    desc 'Show verbose output.'
+    switch %i(v verbose)
+
+    desc 'Show the backtrace when an error occurs.'
+    switch %i(T trace), negatable: false
+
+    desc 'Use the specified Cartage configuration file.'
+    long_desc <<-'DESC'
+Use the specified configuration file. If not specified, the configuration is
+found relative to the current working directory (assumed to be the project
+root) at one of the following locations:
+
+1.  config/cartage.yml
+2.  cartage.yml
+3.  .cartage.yml
+    DESC
+    flag [ :C, 'config-file' ],
+      type: Cartage::Config,
+      arg_name: :FILE,
+      default_value: :'<project-config>'
+
+    desc 'The name of the package.'
+    long_desc <<-'DESC'
+The name of the package is used with the timestamp to create the final package
+name. Defaults to the last part of the repo URL.
+    DESC
+    flag %i(n name), arg_name: :NAME, default_value: :'<repo-name>'
+
+    desc 'The destination of the created package.'
+    long_desc 'Where the final package will be written.'
+    flag %i(t target), arg_name: :PATH, default_value: :tmp
+
+    desc 'The package source root path.'
+    long_desc <<-'DESC'
+Where the package is built from. Defaults to the root of the repository.
+    DESC
+    flag [ :r, 'root-path' ], arg_name: :PATH, default_value: :'<repo-root-path>'
+
+    desc 'The timestamp used for building the package.'
+    long_desc <<-'DESC'
+The timestamp is used with the name of the package is used to create the final
+package name.
+    DESC
+    flag [ :timestamp ], arg_name: :TIMESTAMP
+
+    desc 'Disable the use of vendor dependency caching.'
+    switch [ 'disable-dependency-cache' ], negatable: false
+
+    desc 'The path where vendored dependencies will be cached between builds.'
+    long_desc <<-'DESC'
+Dependencies for deployable packages are vendored. To reduce network calls and
+build time, Cartage will cache the vendored dependencies in a tarball
+(dependency-cache.tar.bz2) in this path.
+    DESC
+    flag [ 'dependency-cache-path' ],
+      arg_name: :PATH,
+      default_value: :'<default-dependency-cache-path>'
+
+    commands_from 'cartage/commands'
+
+    desc 'Save the computed configuration as a configuration file.'
+    arg :'CONFIG-FILE'
+    command '_save' do |save|
+      save.hide!
+
+      save.action do |_global, _options, args|
+        name = args.first
+        name = "#{name}.yml" unless name == '-' || name.end_with?('.yml')
+
+        Cartage::Config.new(cartage.config).tap do |config|
+          config.name ||= cartage.name
+          config.root_path ||= cartage.root_path.to_s
+          config.target ||= cartage.target.to_s
+          config.timestamp ||= cartage.timestamp.to_s
+          config.compression ||= cartage.compression.to_s
+          config.disable_dependency_cache = cartage.disable_dependency_cache
+          config.dependency_cache_path = cartage.dependency_cache_path.to_s
+          config.quiet = cartage.quiet || false
+          config.verbose = cartage.verbose || false
+
+          if name == '-'
+            puts config.to_yaml
+          else
+            Pathname(name).write(config.to_yaml)
+          end
+        end
+      end
+    end
+
+    on_error do |ex|
+      unless ex.kind_of?(Cartage::CLI::QuietExit)
+        output_error_message(ex)
+        ex.backtrace.each { |l| puts l } if backtrace?
+      end
+    end
+
+    pre do |global, _command, _options, _args|
+      self.backtrace = global[:trace]
+
+      clear_defaults_from(global)
+
+      config = case global['config-file']
+               when Cartage::Config
+                 global['config-file']
+               when nil
+                 Cartage::Config.load(:default)
+               else
+                 fail 'Invalid config-file'
+               end
+
+      # Configure Cartage from the config file and global switches.
+      config.disable_dependency_cache ||= global['disable-dependency-cache']
+      config.quiet ||= global['quiet']
+      config.verbose ||= global['verbose']
+
+      config.name = global['name'] if global['name']
+      config.target = global['target'] if global['target']
+      config.root_path = global['root-path'] if global['root-path']
+      config.timestamp = global['timestamp'] if global['timestamp']
+      if global['dependency-cache-path']
+        config.dependency_cache_path = global['dependency-cache-path']
+      end
+
+      cartage(config)
+    end
+  end
+end

data/lib/cartage/commands/echo.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+##
+# Call +extend+ Cartage::CLI to add the commands defined in the block.
+Cartage::CLI.extend do
+  desc 'Echo the provided text'
+  arg :TEXT, :multiple
+  command 'echo' do |echo|
+    echo.hide!
+    echo.desc 'Suppress newlines'
+    echo.switch [ :c, 'no-newlines' ], negatable: false
+    echo.action do |_g, options, args|
+      unless cartage.quiet
+        message = args.join(' ')
+        if options['no-newlines'] || cartage.config(for_command: 'echo').no_newlines
+          puts message
+        else
+          print message
+        end
+      end
+    end
+  end
+end

data/lib/cartage/commands/info.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+##
+# Call +extend+ Cartage::CLI to add the commands defined in the block.
+Cartage::CLI.extend do
+  # Use +desc+ to write a description about the next command.
+  desc 'Show information about Cartage itself'
+
+  # Use +long_desc+ to write a long description about the next command that can
+  # be included in a generated RDoc file.
+  long_desc <<-'DESC'
+Shows various bits of information about Cartage based on the running instance.
+Some plug-ins do run-time resolution of configuration values, so what is shown
+through these subcommands will not represent that resolution.
+  DESC
+
+  # Declare a new command with +command+ and one or more names for the command.
+  # This command is available as both <tt>cartage info</tt> and <tt>cartage
+  # i</tt>. The block contains the definition of the switches, flags,
+  # subcommands, and actions for this command.
+  command %w(info i) do |info|
+    # Use this extension method to hide this command. GLI 2.13 does not support
+    # hiding subcommands.
+    info.hide!
+
+    # The same GLI::DSL works on the command being created, Here, we are
+    # creating <tt>cartage info plugins</tt>.
+    info.desc 'Show the plug-ins that have been found.'
+    info.long_desc <<-'DESC'
+Only plug-ins using the class plug-in protocol are found this way. Plug-ins
+that just provide commands are not reported as plugins.
+    DESC
+    info.command 'plugins' do |plugins|
+      # Implement the #action as a block. It accepts three parameters: the
+      # global options hash, the local command options hash, and any arguments
+      # passed on the command-line.
+      #
+      # Within a command's action, a +cartage+ object is available that
+      # represents the Cartage instance that will be used for packaging.
+      plugins.action do |_global, _options, _args|
+        plugs = cartage.plugins.enabled
+        if plugs.empty?
+          puts 'No active plug-ins.'
+        else
+          plugs.map! do |plug|
+            "* #{plug.plugin_name} (#{plug.version})"
+          end
+          puts <<-plugins
+Active Plug-ins:
+
+#{plugs.join("\n")}
+          plugins
+        end
+      end
+    end
+  end
+end

data/lib/cartage/commands/manifest.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+Cartage::CLI.extend do
+  desc 'Work with the Manifest.txt file'
+  long_desc <<-'DESC'
+Commands that manage the Cartage manifest (Manifest.txt) and ignore
+(.cartignore) files for a project.
+  DESC
+  command 'manifest' do |manifest|
+    manifest.desc 'Check the Manifest.txt file against the current repository'
+    manifest.long_desc <<-'DESC'
+Compares the current Cartage manifest against what would be calculated. If
+there is a difference, it will be displayed in unified ('diff -u') format and a
+non-zero exit status will be returned.
+
+The diff output can be suppressed by specifying -q on cartage:
+
+    cartage -q manifest check
+    DESC
+    manifest.command 'check' do |check|
+      check.action do |_global, _options, _args|
+        cartage.manifest.check or
+          fail Cartage::CLI::QuietExit, $?.exitstatus
+      end
+    end
+
+    manifest.desc 'Install or update the .cartignore file'
+    manifest.long_desc <<-'DESC'
+Creates, replaces, or updates the Cartage ignore file (.cartignore). Will not
+modify an existing .cartignore unless the --mode is overwrite or merge.
+    DESC
+    manifest.command 'cartignore' do |cartignore|
+      cartignore.desc 'Overwrite or merge an existing .cartignore'
+      cartignore.long_desc <<-'DESC'
+Sets the mode for updating the ignore file. When --mode overwrite, the ignore
+file will be replaced with the default ignore file contents. When --mode merge,
+the existing ignore file will be merged with the default ignore file contents.
+      DESC
+      cartignore.flag :mode, must_match: %w(overwrite merge), arg_name: :MODE
+
+      cartignore.desc 'Overwrite an existing .cartignore (--mode overwrite)'
+      cartignore.switch %i(f force overwrite), negatable: false
+
+      cartignore.desc 'Merge an existing .cartignore (--mode merge)'
+      cartignore.switch %i(m merge), negatable: false
+
+      cartignore.action do |_global, options, _args|
+        message = if options['merge'] && options['force']
+                    'Cannot mix options --force and --merge'
+                  elsif options['merge'] && options['mode'] == 'overwrite'
+                    'Cannot mix option --merge and --mode overwrite'
+                  elsif options['force'] && options['mode'] == 'merge'
+                    'Cannot mix option --force and --mode merge'
+                  end
+
+        if message
+          fail Cartage::CLI::CommandException.new(message, cartignore.name_for_help, 64)
+        end
+
+        mode = if options['merge'] || options['mode'] == 'merge'
+                 'merge'
+               elsif options['force'] || options['mode'] == 'overwrite'
+                 'overwrite'
+               end
+
+        cartage.manifest.install_default_ignore(mode: mode)
+      end
+    end
+
+    manifest.desc 'Show the files that will be included in the package'
+    manifest.command 'show' do |show|
+      show.action do |_global, _options, _args|
+        cartage.manifest.resolve do |tmpfile|
+          puts Pathname(tmpfile).read
+        end
+      end
+    end
+
+    manifest.desc 'Generate or update the Manifest.txt file'
+    manifest.command %w(generate update) do |generate|
+      generate.action do |_global, _options, _args|
+        cartage.manifest.generate
+      end
+    end
+
+    manifest.default_command :check
+  end
+end