openbolt 5.0.0.rc1

data/guides/module.yaml

@@ -0,0 +1,18 @@
+---
+topic: module
+guide: |
+    Modules are shareable, reusable packages of Puppet content. They can include
+    tasks, plans, functions, and other types of content that you can use in your
+    project. You can download and install modules to your project from the
+    Puppet Forge or write your own modules. Bolt also ships with several helpful
+    modules pre-installed that are available to all of your projects.
+
+    Bolt makes it easy to manage the modules that your project depends on. You
+    can use Bolt commands to install a project's modules, add new modules to a
+    project, and view the modules that are available to the project.
+    
+    To learn more about managing modules in a project, see the documentation.
+    To learn how modules are loaded by Bolt, see the 'modulepath' guide.
+
+documentation:
+  - https://pup.pt/bolt-modules

data/guides/modulepath.yaml

@@ -0,0 +1,24 @@
+---
+topic: modulepath
+guide: |
+    The modulepath is an ordered list of directories that Bolt loads modules
+    from. When Bolt runs a command, it automatically loads modules from the
+    modulepath.
+    
+    While Bolt has a default modulepath, you can also configure your own
+    modulepath, which can include directories within the project or directories
+    elsewhere on your system. Regardless of whether your project uses a default
+    or configured modulepath, Bolt automatically adds directories to the
+    modulepath. This includes modules containing core Bolt content, which is
+    added to the beginning of the modulepath, and bundled content, which is
+    added to the end of the modulepath.
+
+    Modules loaded from a directory listed earlier in the modulepath take
+    precedence over modules with the same name loaded from a directory later in
+    the modulepath. Bolt will not warn or error when two modules share a name
+    and instead will ignore modules with a lower precedence.
+
+    To learn more about modules, see the 'module' guide.
+
+documentation:
+  - https://pup.pt/bolt-project-reference#modulepath

data/guides/project.yaml

@@ -0,0 +1,21 @@
+---
+topic: project
+guide: |
+    A Bolt project is a directory that serves as the launching point for Bolt
+    and allows you to create a shareable orchestration application. Projects
+    typically include a project configuration file, an inventory file, and any
+    content you use in your project workflow, such as tasks and plans.
+
+    When you run Bolt, it runs in the context of a project. If the directory you
+    run Bolt from is not a project, Bolt attempts to find a project by
+    traversing the parent directories. If Bolt is unable to find a project, it
+    runs from the default project, located at '~/.puppetlabs/bolt'.
+
+    A directory is only considered a Bolt project when it has a project
+    configuration file named 'bolt-project.yaml'. Bolt doesn't load project data
+    and content, including inventory files, unless the data and content are part
+    of a project.
+
+documentation:
+  - https://pup.pt/bolt-projects
+  - https://pup.pt/bolt-project-reference

data/guides/targets.yaml

@@ -0,0 +1,28 @@
+---
+topic: targets
+guide: |
+    A target is a device that Bolt connects to and runs actions on. Targets can
+    be physical, such as servers, or virtual, such as containers or virtual
+    machines.
+
+    Several of Bolt's commands connect to targets and run actions on them.
+    These commands require a target or targets to run on. You can specify
+    targets to a command using one of the following command-line options:
+
+    *nix options                Powershell options
+     -t, --targets TARGETS      -T, -Targets  TARGETS
+     -q, --query   QUERY        -Q, -Query    QUERY
+         --rerun   FILTER       -Rerun        FILTER
+
+    The 'targets' option accepts a comma-separated list of target URIs or group
+    names, or can read a target list from an input file '@<file>' or stdin '-'.
+    URIs can be specified with the format [protocol://][user@]host[:port]. To
+    learn more about available protocols and their defaults, run 'bolt guide
+    transports'.
+
+    Typically, targets and their configuration and data are listed in a
+    project's inventory file. For more information about inventory files,
+    see 'bolt guide inventory'.
+
+documentation:
+  - https://pup.pt/bolt-commands

data/guides/transports.yaml

@@ -0,0 +1,22 @@
+---
+topic: transports
+guide: |
+    Bolt uses transports (also known as protocols) to establish a connection
+    with a target in order to run actions on the target. The default transport is
+    SSH, and you can see available transports along with their configuration
+    options and defaults at http://pup.pt/bolt-reference.
+
+    You can specify a transport for a target by prepending '<transport>://' to
+    the target's URI. For example, to connect to a target with hostname
+    'example.com' as user 'Administrator' using the WinRM transport, you would
+    pass the following to the target flag:
+        winrm://Administrator@example.com
+
+    You can also specify a default transport for all targets by passing the
+    '--transport' flag on *nix systems and the '-Transport' flag in Powershell.
+    Finally, you can set the transport for a target in the inventory. For more
+    information about the Bolt inventory, run 'bolt guide inventory'.
+
+documentation:
+  - https://pup.pt/bolt-commands#specify-a-transport
+  - http://pup.pt/bolt-inventory#transport-configuration

data/lib/bolt/analytics.rb

@@ -0,0 +1,233 @@
+# frozen_string_literal: true
+
+require_relative '../bolt/util'
+require_relative '../bolt/version'
+require 'find'
+require 'json'
+require 'logging'
+require 'securerandom'
+
+module Bolt
+  module Analytics
+    PROTOCOL_VERSION = 1
+    APPLICATION_NAME = 'bolt'
+    TRACKING_ID = 'UA-120367942-1'
+    TRACKING_URL = 'https://google-analytics.com/collect'
+    CUSTOM_DIMENSIONS = {
+      operating_system: :cd1,
+      inventory_nodes: :cd2,
+      inventory_groups: :cd3,
+      target_nodes: :cd4,
+      output_format: :cd5,
+      statement_count: :cd6,
+      resource_mean: :cd7,
+      plan_steps: :cd8,
+      return_type: :cd9,
+      inventory_version: :cd10,
+      boltdir_type: :cd11,
+      puppet_plan_count: :cd12,
+      yaml_plan_count: :cd13
+    }.freeze
+
+    def self.build_client(enabled = true)
+      begin
+        config_file = config_path
+        config = enabled ? load_config(config_file) : {}
+      rescue ArgumentError
+        config = { 'disabled' => true }
+      end
+
+      if !enabled || config['disabled'] || ENV['BOLT_DISABLE_ANALYTICS']
+        Bolt::Logger.debug "Analytics opt-out is set, analytics will be disabled"
+        NoopClient.new
+      else
+        unless config.key?('user-id')
+          config['user-id'] = SecureRandom.uuid
+          write_config(config_file, config)
+        end
+
+        Client.new(config['user-id'])
+      end
+    rescue StandardError => e
+      Bolt::Logger.debug "Failed to initialize analytics client, analytics will be disabled: #{e}"
+      NoopClient.new
+    end
+
+    def self.config_path
+      path     = File.expand_path(File.join('~', '.puppetlabs', 'etc', 'bolt', 'analytics.yaml'))
+      old_path = File.expand_path(File.join('~', '.puppetlabs', 'bolt', 'analytics.yaml'))
+
+      if File.exist?(path)
+        if File.exist?(old_path)
+          message = "Detected analytics configuration files at '#{old_path}' and '#{path}'. Loading "\
+                    "analytics configuration from '#{path}'."
+          Bolt::Logger.warn_once('duplicate_analytics', message)
+        end
+
+        path
+      elsif File.exist?(old_path)
+        old_path
+      else
+        path
+      end
+    end
+
+    def self.load_config(filename)
+      if File.exist?(filename)
+        Bolt::Util.read_optional_yaml_hash(filename, 'analytics')
+      else
+        unless ENV['BOLT_DISABLE_ANALYTICS']
+          msg = <<~ANALYTICS
+            Bolt collects data about how you use it. You can opt out of providing this data.
+            To learn how to disable data collection, or see what data Bolt collects and why,
+            see http://pup.pt/bolt-analytics
+          ANALYTICS
+          Bolt::Logger.warn_once('analytics_opt_out', msg)
+        end
+
+        {}
+      end
+    end
+
+    def self.write_config(filename, config)
+      FileUtils.mkdir_p(File.dirname(filename))
+      File.write(filename, config.to_yaml)
+    rescue StandardError => e
+      Bolt::Logger.warn_once('unwriteable_file', "Could not write analytics configuration to #{filename}.")
+      # This will get caught by build_client and create a NoopClient
+      raise e
+    end
+
+    class Client
+      attr_reader :user_id
+      attr_accessor :bundled_content
+
+      def initialize(user_id)
+        # lazy-load expensive gem code
+        require 'concurrent/configuration'
+        require 'concurrent/future'
+        require 'httpclient'
+        require 'locale'
+
+        @logger = Bolt::Logger.logger(self)
+        @http = HTTPClient.new
+        @user_id = user_id
+        @executor = Concurrent.global_io_executor
+        @os = compute_os
+        @bundled_content = {}
+      end
+
+      def screen_view(screen, **kwargs)
+        custom_dimensions = Bolt::Util.walk_keys(kwargs) do |k|
+          CUSTOM_DIMENSIONS[k] || raise("Unknown analytics key '#{k}'")
+        end
+
+        screen_view_params = {
+          # Type
+          t: 'screenview',
+          # Screen Name
+          cd: screen
+        }.merge(custom_dimensions)
+
+        submit(base_params.merge(screen_view_params))
+      end
+
+      def report_bundled_content(mode, name)
+        if bundled_content[mode.split.first]&.include?(name)
+          event('Bundled Content', mode, label: name)
+        end
+      end
+
+      def event(category, action, label: nil, value: nil, **kwargs)
+        custom_dimensions = Bolt::Util.walk_keys(kwargs) do |k|
+          CUSTOM_DIMENSIONS[k] || raise("Unknown analytics key '#{k}'")
+        end
+
+        event_params = {
+          # Type
+          t: 'event',
+          # Event Category
+          ec: category,
+          # Event Action
+          ea: action
+        }.merge(custom_dimensions)
+
+        # Event Label
+        event_params[:el] = label if label
+        # Event Value
+        event_params[:ev] = value if value
+
+        submit(base_params.merge(event_params))
+      end
+
+      def submit(params)
+        # Handle analytics submission in the background to avoid blocking the
+        # app or polluting the log with errors
+        Concurrent::Future.execute(executor: @executor) do
+          @logger.trace "Submitting analytics: #{JSON.pretty_generate(params)}"
+          @http.post(TRACKING_URL, params)
+          @logger.trace "Completed analytics submission"
+        end
+      end
+
+      # These parameters have terrible names. See this page for complete documentation:
+      # https://developers.google.com/analytics/devguides/collection/protocol/v1/parameters
+      def base_params
+        {
+          v: PROTOCOL_VERSION,
+          # Client ID
+          cid: @user_id,
+          # Tracking ID
+          tid: TRACKING_ID,
+          # Application Name
+          an: APPLICATION_NAME,
+          # Application Version
+          av: Bolt::VERSION,
+          # Anonymize IPs
+          aip: true,
+          # User locale
+          ul: Locale.current.to_rfc,
+          # Custom Dimension 1 (Operating System)
+          cd1: @os
+        }
+      end
+
+      def compute_os
+        require 'facter'
+        os = Facter.value('os')
+        "#{os['name']} #{os.dig('release', 'major')}"
+      end
+
+      # If the user is running a very fast command, there may not be time for
+      # analytics submission to complete before the command is finished. In
+      # that case, we give a little buffer for any stragglers to finish up.
+      # 250ms strikes a balance between accomodating slower networks while not
+      # introducing a noticeable "hang".
+      def finish
+        @executor.shutdown
+        @executor.wait_for_termination(0.25)
+      end
+    end
+
+    class NoopClient
+      attr_accessor :bundled_content
+
+      def initialize
+        @logger = Bolt::Logger.logger(self)
+        @bundled_content = []
+      end
+
+      def screen_view(screen, **_kwargs)
+        @logger.trace "Skipping submission of '#{screen}' screenview because analytics is disabled"
+      end
+
+      def report_bundled_content(mode, name); end
+
+      def event(category, action, **_kwargs)
+        @logger.trace "Skipping submission of '#{category} #{action}' event because analytics is disabled"
+      end
+
+      def finish; end
+    end
+  end
+end