ruby-pwsh 0.4.1 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2fcc279675091bc4fcf7b31a7f309561c49b14352895424f72ca9170ffd51de3
-  data.tar.gz: 2c1160616d59bc30f1a641469617e0b941e610bf48e8c640a1de2a95df66778c
+  metadata.gz: 83a03013a6f1fd8f72b90d29d76f211cf1fbba6f32a8e5275bc7b9ce29d7a52a
+  data.tar.gz: 8ce907ddb3d833eec4a193ce994e05a990ccc2f20e46518674896efa14bd6328
 SHA512:
-  metadata.gz: f957369ca4ed3b5932c843195bd9ec20614dd7211b8f0fd1e1ed76833aa8912d897a5341d605c89b95e7b76a9ba623c3064709e2ed1182415dbb907285d61dbd
-  data.tar.gz: 7508304850d8663c31f8ce420accf3a3007e594176365199ddb910e50a383ab7dc2b7e17911213c3fc5cea66eafcfb4ae89b7554f03b47df94fcd81483cad056
+  metadata.gz: 71abf1b0cc94d5f742ae6240d08fff15f86e588157a4a482501f2383ac11e5f3644fb43702af5071720193303fa803debeed362bb20f2efec205b0137acb115e
+  data.tar.gz: b9c9ce3518e6cbc27c6b0f8126519a1c1ea53158424f72162b75e23ecd28415e80cf5df4e9dc762aadd93a99e30e16a5a91dc405cd9d8571a53184bbe04e4373

data/.rubocop.yml

@@ -1,3 +1,5 @@
+Gemspec/RequiredRubyVersion:
+  Enabled: false
 Layout/EndOfLine:
   Description: Don't enforce CRLF on Windows.
   Enabled: false
@@ -28,4 +30,12 @@ Naming/FileName:
 Style/RescueStandardError:
   Enabled: false
 Style/ExpandPathArguments:
-  Enabled: false
+  Enabled: false
+Style/Documentation:
+  Enabled: false
+Style/ClassAndModuleChildren:
+  Exclude:
+    - lib/puppet/provider/dsc_base_provider/dsc_base_provider.rb
+Style/ClassVars:
+  Exclude:
+    - lib/puppet/provider/dsc_base_provider/dsc_base_provider.rb

data/.travis.yml

@@ -19,6 +19,7 @@ script:
   - 'bundle exec rake $CHECK'
 rvm:
   - 2.5.1
+  - 2.7
 matrix:
   include:
   - env: CHECK="rubocop"

data/CHANGELOG.md

@@ -2,7 +2,15 @@
 
 All notable changes to this project will be documented in this file.The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/) and this project adheres to [Semantic Versioning](http://semver.org).
 
-## [0.4.1](https://github.com/puppetlabs/ruby-pwsh/tree/0.4.1) (2020-02-12)
+## [0.5.0](https://github.com/puppetlabs/ruby-pwsh/tree/0.5.0) (2020-08-20)
+
+[Full Changelog](https://github.com/puppetlabs/ruby-pwsh/compare/0.4.1...0.5.0)
+
+### Added
+
+- \(IAC-1045\) Add the DSC base Puppet provider to pwshlib [\#39](https://github.com/puppetlabs/ruby-pwsh/pull/39) ([michaeltlombardi](https://github.com/michaeltlombardi))
+
+## [0.4.1](https://github.com/puppetlabs/ruby-pwsh/tree/0.4.1) (2020-02-13)
 
 [Full Changelog](https://github.com/puppetlabs/ruby-pwsh/compare/0.4.0...0.4.1)
 
@@ -16,7 +24,7 @@ All notable changes to this project will be documented in this file.The format i
 
 ### Added
 
-- \(MODULES-10389\) Add puppet feature for dependent modules to leverage [\#20](https://github.com/puppetlabs/ruby-pwsh/pull/20) ([cmccrisken-puppet](https://github.com/cmccrisken-puppet))
+- \(MODULES-10389\) Add puppet feature for dependent modules to leverage [\#20](https://github.com/puppetlabs/ruby-pwsh/pull/20) ([sanfrancrisko](https://github.com/sanfrancrisko))
 
 ## [0.3.0](https://github.com/puppetlabs/ruby-pwsh/tree/0.3.0) (2019-12-04)
 
@@ -41,4 +49,4 @@ All notable changes to this project will be documented in this file.The format i
 
 
 
-\* *This Changelog was automatically generated by [github_changelog_generator](https://github.com/skywinder/Github-Changelog-Generator)*
+\* *This Changelog was automatically generated by [github_changelog_generator](https://github.com/github-changelog-generator/github-changelog-generator)*

data/Gemfile

@@ -17,25 +17,20 @@ group :test do
 end
 
 group :development do
-  # TODO: Use gem instead of git. Section mapping is merged into master, but not yet released
-  gem 'github_changelog_generator', git: 'https://github.com/skywinder/github-changelog-generator.git', ref: '20ee04ba1234e9e83eb2ffb5056e23d641c7a018'
+  gem 'github_changelog_generator', '~> 1.15' if Gem::Version.new(RUBY_VERSION.dup) >= Gem::Version.new('2.3.0')
   gem 'yard'
 end
 
 group :puppet do
   gem 'pdk', '~> 1.0'
+  gem 'puppet'
 end
 
 group :pry do
   gem 'fuubar'
 
-  if RUBY_VERSION == '1.8.7'
-    gem 'debugger'
-  elsif RUBY_VERSION =~ /^2\.[01]/
-    gem 'byebug', '~> 9.0.0'
+  if Gem::Version.new(RUBY_VERSION.dup) >= Gem::Version.new('2.4.0')
     gem 'pry-byebug'
-  elsif RUBY_VERSION =~ /^2\.[23456789]/
-    gem 'pry-byebug' # rubocop:disable Bundler/DuplicatedGem
   else
     gem 'pry-debugger'
   end

data/README.md

@@ -70,4 +70,50 @@ After checking out the repo, run `bin/setup` to install dependencies. Then, run
 
 To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org). -->
 
+## Releasing the Gem and Puppet Module
+
+Steps to release an update to the gem and module include:
+
+1. Ensure that the release branch is up to date with the master:
+   ```bash
+   git push upstream upstream/master:release --force
+   ```
+1. Checkout a new working branch for the release prep (where xyz is the appropriate version, sans periods):
+   ```bash
+   git checkout -b maint/release/prep-xyz upstream/release
+   ```
+1. Update the version in `lib/pwsh/version.rb` and `metadata.json` to the appropriate version for the new release.
+1. Run the changelog update task (make sure to verify the changelog, correctly tagging PRs as needed):
+   ```bash
+   bundle exec rake changelog
+   ```
+1. Commit your changes with a short, sensible commit message, like:
+   ```text
+   git add lib/pwsh/version.rb
+   git add metadata.json
+   git add CHANGELOG.md
+   git commit -m '(MAINT) Prep for x.y.z release'
+   ```
+1. Push your changes and submit a pull request for review _against the **release** branch_:
+   ```bash
+   git push -u origin maint/release-prep-xyz
+   ```
+1. Ensure tests pass and the code is merged to `release`.
+1. Grab the commit hash from the merge commit on release, use that as the tag for the version (replacing `x.y.z` with the appropriate version and  `commithash` with the relevant one), then push the tags to upstream:
+   ```bash
+   bundle exec rake tag['x.y.z', 'commithash']
+   ```
+1. Build the Ruby gem and publish:
+   ```bash
+   bundle exec rake build
+   bundle exec rake push['ruby-pwsh-x.y.z.gem']
+   ```
+1. Verify that the correct version now exists on [RubyGems](https://rubygems.org/search?query=ruby-pwsh)
+1. Build the Puppet module:
+   ```bash
+   bundle exec rake build_module
+   ```
+1. Publish the updated module version (found in the `pkg` folder) to [the Forge](https://forge.puppet.com/puppetlabs/pwshlib).
+1. Submit the [mergeback PR from the release branch to master](https://github.com/puppetlabs/ruby-pwsh/compare/master...release).
+
 ## Known Issues

data/appveyor.yml

@@ -0,0 +1,38 @@
+---
+version: 1.1.x.{build}
+branches:
+  only:
+    - master
+    - release
+clone_depth: 10
+environment:
+  matrix:
+    -
+      RUBY_VERSION: 25-x64
+      CHECK: rubocop
+    -
+      RUBY_VERSION: 25
+      CHECK: spec
+      COVERAGE: yes
+matrix:
+  fast_finish: true
+install:
+  - set PATH=C:\Ruby%RUBY_VERSION%\bin;%PATH%
+  - bundle install --jobs 4 --retry 2
+  - type Gemfile.lock
+build: off
+build_script:
+  - dir .
+test_script:
+  - ruby -v
+  - gem -v
+  - bundle -v
+  - pwsh -v
+  - bundle exec rake %CHECK%
+notifications:
+  - provider: Email
+    to:
+      - nobody@nowhere.com
+    on_build_success: false
+    on_build_failure: false
+    on_build_status_changed: false

data/lib/puppet/provider/dsc_base_provider/dsc_base_provider.rb

@@ -0,0 +1,666 @@
+# frozen_string_literal: true
+
+require 'puppet/resource_api/simple_provider'
+require 'securerandom'
+require 'ruby-pwsh'
+require 'pathname'
+require 'json'
+
+class Puppet::Provider::DscBaseProvider < Puppet::ResourceApi::SimpleProvider
+  # Initializes the provider, preparing the class variables which cache:
+  # - the canonicalized resources across calls
+  # - query results
+  # - logon failures
+  def initialize
+    @@cached_canonicalized_resource = []
+    @@cached_query_results = []
+    @@logon_failures = []
+  end
+
+  # Look through a cache to retrieve the hashes specified, if they have been cached.
+  # Does so by seeing if each of the specified hashes is a subset of any of the hashes
+  # in the cache, so {foo: 1, bar: 2} would return if {foo: 1} was the search hash.
+  #
+  # @param cache [Array] the class variable containing cached hashes to search through
+  # @param hashes [Array] the list of hashes to search the cache for
+  # @return [Array] an array containing the matching hashes for the search condition, if any
+  def fetch_cached_hashes(cache, hashes)
+    cache.reject do |item|
+      matching_hash = hashes.select { |hash| (item.to_a - hash.to_a).empty? || (hash.to_a - item.to_a).empty? }
+      matching_hash.empty?
+    end.flatten
+  end
+
+  # Implements the canonicalize feature of the Resource API; this method is called first against any resources
+  # defined in the manifest, then again to conform the results from a get call. The method attempts to retrieve
+  # the DSC resource from the machine; if the resource is found, this method then compares the downcased values
+  # of the two hashes, overwriting the manifest value with the discovered one if they are case insensitively
+  # equivalent; this enables case insensitive but preserving behavior where a manifest declaration of a path as
+  # "c:/foo/bar" if discovered on disk as "C:\Foo\Bar" will canonicalize to the latter and prevent any flapping.
+  #
+  # @param context [Object] the Puppet runtime context to operate in and send feedback to
+  # @param resources [Hash] the hash of the resource to canonicalize from either manifest or invocation
+  # @return [Hash] returns a hash representing the current state of the object, if it exists
+  def canonicalize(context, resources)
+    canonicalized_resources = []
+    resources.collect do |r|
+      if fetch_cached_hashes(@@cached_canonicalized_resource, [r]).empty?
+        canonicalized = invoke_get_method(context, r)
+        if canonicalized.nil?
+          canonicalized = r.dup
+          @@cached_canonicalized_resource << r.dup
+        else
+          canonicalized[:name] = r[:name]
+          if r[:dsc_psdscrunascredential].nil?
+            canonicalized.delete(:dsc_psdscrunascredential)
+          else
+            canonicalized[:dsc_psdscrunascredential] = r[:dsc_psdscrunascredential]
+          end
+          downcased_result = recursively_downcase(canonicalized)
+          downcased_resource = recursively_downcase(r)
+          downcased_result.each do |key, value|
+            canonicalized[key] = r[key] unless downcased_resource[key] == value
+            canonicalized.delete(key) unless downcased_resource.keys.include?(key)
+          end
+          # Cache the actually canonicalized resource separately
+          @@cached_canonicalized_resource << canonicalized.dup
+        end
+      else
+        canonicalized = r
+      end
+      canonicalized_resources << canonicalized
+    end
+    context.debug("Canonicalized Resources: #{canonicalized_resources}")
+    canonicalized_resources
+  end
+
+  # Attempts to retrieve an instance of the DSC resource, invoking the `Get` method and passing any
+  # namevars as the Properties to Invoke-DscResource. The result object, if any, is compared to the
+  # specified properties in the Puppet Resource to decide whether it needs to be created, updated,
+  # deleted, or whether it is in the desired state.
+  #
+  # @param context [Object] the Puppet runtime context to operate in and send feedback to
+  # @param names [Hash] the hash of namevar properties and their values to use to get the resource
+  # @return [Hash] returns a hash representing the current state of the object, if it exists
+  def get(context, names = nil)
+    # Relies on the get_simple_filter feature to pass the namevars
+    # as an array containing the namevar parameters as a hash.
+    # This hash is functionally the same as a should hash as
+    # passed to the should_to_resource method.
+    context.debug('Collecting data from the DSC Resource')
+
+    # If the resource has already been queried, do not bother querying for it again
+    cached_results = fetch_cached_hashes(@@cached_query_results, names)
+    return cached_results unless cached_results.empty?
+
+    if @@cached_canonicalized_resource.empty?
+      mandatory_properties = {}
+    else
+      canonicalized_resource = @@cached_canonicalized_resource[0].dup
+      mandatory_properties = canonicalized_resource.select do |attribute, _value|
+        (mandatory_get_attributes(context) - namevar_attributes(context)).include?(attribute)
+      end
+      # If dsc_psdscrunascredential was specified, re-add it here.
+      mandatory_properties[:dsc_psdscrunascredential] = canonicalized_resource[:dsc_psdscrunascredential] if canonicalized_resource.keys.include?(:dsc_psdscrunascredential)
+    end
+    names.collect do |name|
+      name = { name: name } if name.is_a? String
+      invoke_get_method(context, name.merge(mandatory_properties))
+    end
+  end
+
+  # Attempts to set an instance of the DSC resource, invoking the `Set` method and thinly wrapping
+  # the `invoke_set_method` method; whether this method, `update`, or `delete` is called is entirely
+  # up to the Resource API based on the results
+  #
+  # @param context [Object] the Puppet runtime context to operate in and send feedback to
+  # @param name [String] the name of the resource being created
+  # @return [Hash] returns a hash indicating whether or not the resource is in the desired state, whether or not it requires a reboot, and any error messages captured.
+  def create(context, name, should)
+    context.debug("Creating '#{name}' with #{should.inspect}")
+    invoke_set_method(context, name, should)
+  end
+
+  # Attempts to set an instance of the DSC resource, invoking the `Set` method and thinly wrapping
+  # the `invoke_set_method` method; whether this method, `create`, or `delete` is called is entirely
+  # up to the Resource API based on the results
+  #
+  # @param context [Object] the Puppet runtime context to operate in and send feedback to
+  # @param name [String] the name of the resource being created
+  # @return [Hash] returns a hash indicating whether or not the resource is in the desired state, whether or not it requires a reboot, and any error messages captured.
+  def update(context, name, should)
+    context.debug("Updating '#{name}' with #{should.inspect}")
+    invoke_set_method(context, name, should)
+  end
+
+  # Attempts to set an instance of the DSC resource, invoking the `Set` method and thinly wrapping
+  # the `invoke_set_method` method; whether this method, `create`, or `update` is called is entirely
+  # up to the Resource API based on the results
+  #
+  # @param context [Object] the Puppet runtime context to operate in and send feedback to
+  # @param name [String] the name of the resource being created
+  # @return [Hash] returns a hash indicating whether or not the resource is in the desired state, whether or not it requires a reboot, and any error messages captured.
+  def delete(context, name)
+    context.debug("Deleting '#{name}'")
+    invoke_set_method(context, name, name.merge({ dsc_ensure: 'Absent' }))
+  end
+
+  # Invokes the `Get` method, passing the name_hash as the properties to use with `Invoke-DscResource`
+  # The PowerShell script returns a JSON representation of the DSC Resource's CIM Instance munged as
+  # best it can be for Ruby. Once that JSON is parsed into a hash this method further munges it to
+  # fit the expected property definitions. Finally, it returns the object for the Resource API to
+  # compare against and determine what future actions, if any, are needed.
+  #
+  # @param context [Object] the Puppet runtime context to operate in and send feedback to
+  # @param name_hash [Hash] the hash of namevars to be passed as properties to `Invoke-DscResource`
+  # @return [Hash] returns a hash representing the DSC resource munged to the representation the Puppet Type expects
+  def invoke_get_method(context, name_hash)
+    context.debug("retrieving #{name_hash.inspect}")
+
+    # Do not bother running if the logon credentials won't work
+    unless name_hash[:dsc_psdscrunascredential].nil?
+      return name_hash if logon_failed_already?(name_hash[:dsc_psdscrunascredential])
+    end
+
+    query_props = name_hash.select { |k, v| mandatory_get_attributes(context).include?(k) || (k == :dsc_psdscrunascredential && !v.nil?) }
+    resource = should_to_resource(query_props, context, 'get')
+    script_content = ps_script_content(resource)
+    context.debug("Script:\n #{redact_secrets(script_content)}")
+    output = ps_manager.execute(script_content)[:stdout]
+    context.err('Nothing returned') if output.nil?
+
+    data = JSON.parse(output)
+    context.debug("raw data received: #{data.inspect}")
+    error = data['errormessage']
+    unless error.nil?
+      # NB: We should have a way to stop processing this resource *now* without blowing up the whole Puppet run
+      # Raising an error stops processing but blows things up while context.err alerts but continues to process
+      if error =~ /Logon failure: the user has not been granted the requested logon type at this computer/
+        logon_error = "PSDscRunAsCredential account specified (#{name_hash[:dsc_psdscrunascredential]['user']}) does not have appropriate logon rights; are they an administrator?"
+        name_hash[:name].nil? ? context.err(logon_error) : context.err(name_hash[:name], logon_error)
+        @@logon_failures << name_hash[:dsc_psdscrunascredential].dup
+        # This is a hack to handle the query cache to prevent a second lookup
+        @@cached_query_results << name_hash # if fetch_cached_hashes(@@cached_query_results, [data]).empty?
+      else
+        context.err(error)
+      end
+      # Either way, something went wrong and we didn't get back a good result, so return nil
+      return nil
+    end
+    # DSC gives back information we don't care about; filter down to only
+    # those properties exposed in the type definition.
+    valid_attributes = context.type.attributes.keys.collect(&:to_s)
+    data.select! { |key, _value| valid_attributes.include?("dsc_#{key.downcase}") }
+    # Canonicalize the results to match the type definition representation;
+    # failure to do so will prevent the resource_api from comparing the result
+    # to the should hash retrieved from the resource definition in the manifest.
+    data.keys.each do |key|
+      type_key = "dsc_#{key.downcase}".to_sym
+      data[type_key] = data.delete(key)
+      camelcase_hash_keys!(data[type_key]) if data[type_key].is_a?(Enumerable)
+    end
+    # If a resource is found, it's present, so refill these two Puppet-only keys
+    data.merge!({ name: name_hash[:name] })
+    if ensurable?(context)
+      ensure_value = data.key?(:dsc_ensure) ? data[:dsc_ensure].downcase : 'present'
+      data.merge!({ ensure: ensure_value })
+    end
+    # TODO: Handle PSDscRunAsCredential flapping
+    # Resources do not return the account under which they were discovered, so re-add that
+    if name_hash[:dsc_psdscrunascredential].nil?
+      data.delete(:dsc_psdscrunascredential)
+    else
+      data.merge!({ dsc_psdscrunascredential: name_hash[:dsc_psdscrunascredential] })
+    end
+    # Cache the query to prevent a second lookup
+    @@cached_query_results << data.dup if fetch_cached_hashes(@@cached_query_results, [data]).empty?
+    context.debug("Returned to Puppet as #{data}")
+    data
+  end
+
+  # Invokes the `Set` method, passing the should hash as the properties to use with `Invoke-DscResource`
+  # The PowerShell script returns a JSON hash with key-value pairs indicating whether or not the resource
+  # is in the desired state, whether or not it requires a reboot, and any error messages captured.
+  #
+  # @param context [Object] the Puppet runtime context to operate in and send feedback to
+  # @param should [Hash] the desired state represented definition to pass as properties to Invoke-DscResource
+  # @return [Hash] returns a hash indicating whether or not the resource is in the desired state, whether or not it requires a reboot, and any error messages captured.
+  def invoke_set_method(context, name, should)
+    context.debug("Invoking Set Method for '#{name}' with #{should.inspect}")
+
+    # Do not bother running if the logon credentials won't work
+    unless should[:dsc_psdscrunascredential].nil?
+      return nil if logon_failed_already?(should[:dsc_psdscrunascredential])
+    end
+
+    apply_props = should.select { |k, _v| k.to_s =~ /^dsc_/ }
+    resource = should_to_resource(apply_props, context, 'set')
+    script_content = ps_script_content(resource)
+    context.debug("Script:\n #{redact_secrets(script_content)}")
+
+    output = ps_manager.execute(script_content)[:stdout]
+    context.err('Nothing returned') if output.nil?
+
+    data = JSON.parse(output)
+    context.debug(data)
+
+    context.err(data['errormessage']) unless data['errormessage'].empty?
+    # TODO: Implement this functionality for notifying a DSC reboot?
+    # notify_reboot_pending if data['rebootrequired'] == true
+    data
+  end
+
+  # Converts a Puppet resource hash into a hash with the information needed to call Invoke-DscResource,
+  # including the desired state, the path to the PowerShell module containing the resources, the invoke
+  # method, and metadata about the DSC Resource and Puppet Type.
+  #
+  # @param should [Hash] A hash representing the desired state of the DSC resource as defined in Puppet
+  # @param context [Object] the Puppet runtime context to operate in and send feedback to
+  # @param dsc_invoke_method [String] the method to pass to Invoke-DscResource: get, set, or test
+  # @return [Hash] a hash with the information needed to run `Invoke-DscResource`
+  def should_to_resource(should, context, dsc_invoke_method)
+    resource = {}
+    resource[:parameters] = {}
+    %i[name dscmeta_resource_friendly_name dscmeta_resource_name dscmeta_module_name dscmeta_module_version].each do |k|
+      resource[k] = context.type.definition[k]
+    end
+    should.each do |k, v|
+      next if k == :ensure
+      # PSDscRunAsCredential is considered a namevar and will always be passed, even if nil
+      # To prevent flapping during runs, remove it from the resource definition unless specified
+      next if k == :dsc_psdscrunascredential && v.nil?
+
+      resource[:parameters][k] = {}
+      resource[:parameters][k][:value] = v
+      %i[mof_type mof_is_embedded].each do |ky|
+        resource[:parameters][k][ky] = context.type.definition[:attributes][k][ky]
+      end
+    end
+    resource[:dsc_invoke_method] = dsc_invoke_method
+
+    # Because Puppet adds all of the modules to the LOAD_PATH we can be sure that the appropriate module lives here
+    # PROBLEM: This currently uses the downcased name, we need to capture the module name in the metadata I think.
+    root_module_path = $LOAD_PATH.select { |path| path.match?(%r{#{resource[:dscmeta_module_name].downcase}/lib}) }.first
+    resource[:vendored_modules_path] = File.expand_path(root_module_path + '/puppet_x/dsc_resources')
+    # resource[:vendored_modules_path] = File.expand_path(Pathname.new(__FILE__).dirname + '../../../' + 'puppet_x/dsc_resources')
+    resource[:attributes] = nil
+    context.debug("should_to_resource: #{resource.inspect}")
+    resource
+  end
+
+  # Return a UUID with the dashes turned into underscores to enable the specifying of guaranteed-unique
+  # variables in the PowerShell script.
+  #
+  # @return [String] a uuid with underscores instead of dashes.
+  def random_variable_name
+    # PowerShell variables can't include dashes
+    SecureRandom.uuid.gsub('-', '_')
+  end
+
+  # Return a Hash containing all of the variables defined for instantiation as well as the Ruby hash for their
+  # properties so they can be matched and replaced as needed.
+  #
+  # @return [Hash] containing all instantiated variables and the properties that they define
+  def instantiated_variables
+    @@instantiated_variables ||= {}
+  end
+
+  # Clear the instantiated variables hash to be ready for the next run
+  def clear_instantiated_variables!
+    @@instantiated_variables = {}
+  end
+
+  # Return true if the specified credential hash has already failed to execute a DSC resource due to
+  # a logon error, as when the account is not an administrator on the machine; otherwise returns false.
+  #
+  # @param [Hash] a credential hash with a user and password keys where the password is a sensitive string
+  # @return [Bool] true if the credential_hash has already failed logon, false otherwise
+  def logon_failed_already?(credential_hash)
+    @@logon_failures.any? do  |failure_hash|
+      failure_hash['user'] == credential_hash['user'] && failure_hash['password'].unwrap == credential_hash['password'].unwrap
+    end
+  end
+
+  # Recursively transforms any enumerable, camelCasing any hash keys it finds
+  #
+  # @param enumerable [Enumerable] a string, array, hash, or other object to attempt to recursively downcase
+  # @return [Enumerable] returns the input object with hash keys recursively camelCased
+  def camelcase_hash_keys!(enumerable)
+    if enumerable.is_a?(Hash)
+      enumerable.keys.each do |key|
+        name = key.dup
+        name[0] = name[0].downcase
+        enumerable[name] = enumerable.delete(key)
+        camelcase_hash_keys!(enumerable[name]) if enumerable[name].is_a?(Enumerable)
+      end
+    else
+      enumerable.each { |item| camelcase_hash_keys!(item) if item.is_a?(Enumerable) }
+    end
+  end
+
+  # Recursively transforms any object, downcasing it to enable case insensitive comparisons
+  #
+  # @param object [Object] a string, array, hash, or other object to attempt to recursively downcase
+  # @return [Object] returns the input object recursively downcased
+  def recursively_downcase(object)
+    case object
+    when String
+      object.downcase
+    when Array
+      object.map { |item| recursively_downcase(item) }
+    when Hash
+      transformed = {}
+      object.transform_keys(&:downcase).each do |key, value|
+        transformed[key] = recursively_downcase(value)
+      end
+      transformed
+    else
+      object
+    end
+  end
+
+  # Checks to see whether the DSC resource being managed is defined as ensurable
+  #
+  # @param context [Object] the Puppet runtime context to operate in and send feedback to
+  # @return [Bool] returns true if the DSC Resource is ensurable, otherwise false.
+  def ensurable?(context)
+    context.type.attributes.keys.include?(:ensure)
+  end
+
+  # Parses the DSC resource type definition to retrieve the names of any attributes which are specified as mandatory for get operations
+  #
+  # @param context [Object] the Puppet runtime context to operate in and send feedback to
+  # @return [Array] returns an array of attribute names as symbols which are mandatory for get operations
+  def mandatory_get_attributes(context)
+    context.type.attributes.select { |_attribute, properties| properties[:mandatory_for_get] }.keys
+  end
+
+  # Parses the DSC resource type definition to retrieve the names of any attributes which are specified as mandatory for set operations
+  #
+  # @param context [Object] the Puppet runtime context to operate in and send feedback to
+  # @return [Array] returns an array of attribute names as symbols which are mandatory for set operations
+  def mandatory_set_attributes(context)
+    context.type.attributes.select { |_attribute, properties| properties[:mandatory_for_set] }.keys
+  end
+
+  # Parses the DSC resource type definition to retrieve the names of any attributes which are specified as namevars
+  #
+  # @param context [Object] the Puppet runtime context to operate in and send feedback to
+  # @return [Array] returns an array of attribute names as symbols which are namevars
+  def namevar_attributes(context)
+    context.type.attributes.select { |_attribute, properties| properties[:behaviour] == :namevar }.keys
+  end
+
+  # Look through a fully formatted string, replacing all instances where a value matches the formatted properties
+  # of an instantiated variable with references to the variable instead. This allows us to pass complex and nested
+  # CIM instances to the Invoke-DscResource parameter hash without constructing them *in* the hash.
+  #
+  # @param string [String] the string of text to search through for places an instantiated variable can be referenced
+  # @return [String] the string with references to instantiated variables instead of their properties
+  def interpolate_variables(string)
+    modified_string = string
+    # Always replace later-created variables first as they sometimes were built from earlier ones
+    instantiated_variables.reverse_each do |variable_name, ruby_definition|
+      modified_string = modified_string.gsub(format(ruby_definition), "$#{variable_name}")
+    end
+    modified_string
+  end
+
+  # Parses a resource definition (as from `should_to_resource`) for any properties which are PowerShell
+  # Credentials. As these values need to be serialized into PSCredential objects, return an array of
+  # PowerShell lines, each of which instantiates a variable which holds the value as a PSCredential.
+  # These credential variables can then be simply assigned in the parameter hash where needed.
+  #
+  # @param resource [Hash] a hash with the information needed to run `Invoke-DscResource`
+  # @return [String] An array of lines of PowerShell to instantiate PSCredentialObjects and store them in variables
+  def prepare_credentials(resource)
+    credentials_block = []
+    resource[:parameters].each do |_property_name, property_hash|
+      next unless property_hash[:mof_type] == 'PSCredential'
+      next if property_hash[:value].nil?
+
+      variable_name = random_variable_name
+      credential_hash = {
+        'user' => property_hash[:value]['user'],
+        'password' => escape_quotes(property_hash[:value]['password'].unwrap)
+      }
+      instantiated_variables.merge!(variable_name => credential_hash)
+      credentials_block << format_pscredential(variable_name, credential_hash)
+    end
+    credentials_block.join("\n")
+    credentials_block == [] ? '' : credentials_block
+  end
+
+  # Write a line of PowerShell which creates a PSCredential object and assigns it to a variable
+  #
+  # @param variable_name [String] the name of the Variable to assign the PSCredential object to
+  # @param credential_hash [Hash] the Properties which define the PSCredential Object
+  # @return [String] A line of PowerShell which defines the PSCredential object and stores it to a variable
+  def format_pscredential(variable_name, credential_hash)
+    definition = "$#{variable_name} = New-PSCredential -User #{credential_hash['user']} -Password '#{credential_hash['password']}' # PuppetSensitive"
+    definition
+  end
+
+  # Parses a resource definition (as from `should_to_resource`) for any properties which are CIM instances
+  # whether at the top level or nested inside of other CIM instances, and, where they are discovered, adds
+  # those objects to the instantiated_variables hash as well as returning a line of PowerShell code which
+  # will create the CIM object and store it in a variable. This then allows the CIM instances to be assigned
+  # by variable reference.
+  #
+  # @param resource [Hash] a hash with the information needed to run `Invoke-DscResource`
+  # @return [String] An array of lines of PowerShell to instantiate CIM Instances and store them in variables
+  def prepare_cim_instances(resource)
+    cim_instances_block = []
+    resource[:parameters].each do |_property_name, property_hash|
+      next unless property_hash[:mof_is_embedded]
+
+      # strip dsc_ from the beginning of the property name declaration
+      # name = property_name.to_s.gsub(/^dsc_/, '').to_sym
+      # Process nested CIM instances first as those neeed to be passed to higher-order
+      # instances and must therefore be declared before they must be referenced
+      cim_instance_hashes = nested_cim_instances(property_hash[:value]).flatten.reject(&:nil?)
+      # Sometimes the instances are an empty array
+      unless cim_instance_hashes.count.zero?
+        cim_instance_hashes.each do |instance|
+          variable_name = random_variable_name
+          instantiated_variables.merge!(variable_name => instance)
+          class_name = instance['cim_instance_type']
+          properties = instance.reject { |k, _v| k == 'cim_instance_type' }
+          cim_instances_block << format_ciminstance(variable_name, class_name, properties)
+        end
+      end
+      # We have to handle arrays of CIM instances slightly differently
+      if property_hash[:mof_type] =~ /\[\]$/
+        class_name = property_hash[:mof_type].gsub('[]', '')
+        property_hash[:value].each do |hash|
+          variable_name = random_variable_name
+          instantiated_variables.merge!(variable_name => hash)
+          cim_instances_block << format_ciminstance(variable_name, class_name, hash)
+        end
+      else
+        variable_name = random_variable_name
+        instantiated_variables.merge!(variable_name => property_hash[:value])
+        class_name = property_hash[:mof_type]
+        cim_instances_block << format_ciminstance(variable_name, class_name, property_hash[:value])
+      end
+    end
+    cim_instances_block == [] ? '' : cim_instances_block.join("\n")
+  end
+
+  # Recursively search for and return CIM instances nested in an enumerable
+  #
+  # @param enumerable [Enumerable] a hash or array which may contain CIM Instances
+  # @return [Hash] every discovered hash which does define a CIM Instance
+  def nested_cim_instances(enumerable)
+    enumerable.collect do |key, value|
+      if key.is_a?(Hash) && key.key?('cim_instance_type')
+        key
+        # TODO: Are there any cim instancees 3 levels deep, or only 2?
+        # if so, we should *also* keep searching and processing...
+      elsif key.is_a?(Enumerable)
+        nested_cim_instances(key)
+      elsif value.is_a?(Enumerable)
+        nested_cim_instances(value)
+      end
+    end
+  end
+
+  # Write a line of PowerShell which creates a CIM Instance and assigns it to a variable
+  #
+  # @param variable_name [String] the name of the Variable to assign the CIM Instance to
+  # @param class_name [String] the CIM Class to instantiate
+  # @param property_hash [Hash] the Properties which define the CIM Instance
+  # @return [String] A line of PowerShell which defines the CIM Instance and stores it to a variable
+  def format_ciminstance(variable_name, class_name, property_hash)
+    definition = "$#{variable_name} = New-CimInstance -ClientOnly -ClassName '#{class_name}' -Property #{format(property_hash)}"
+    # AWFUL HACK to make New-CimInstance happy ; it can't parse an array unless it's an array of Cim Instances
+    # definition = definition.gsub("@(@{'cim_instance_type'","[CimInstance[]]@(@{'cim_instance_type'")
+    # EVEN WORSE HACK - this one we can't even be sure it's a cim instance...
+    # but I don't _think_ anything but nested cim instances show up as hashes inside an array
+    definition = definition.gsub('@(@{', '[CimInstance[]]@(@{')
+    definition = interpolate_variables(definition)
+    definition
+  end
+
+  # Munge a resource definition (as from `should_to_resource`) into valid PowerShell which represents
+  # the `InvokeParams` hash which will be splatted to `Invoke-DscResource`, interpolating all previously
+  # defined variables into the hash.
+  #
+  # @param resource [Hash] a hash with the information needed to run `Invoke-DscResource`
+  # @return [String] A string representing the PowerShell definition of the InvokeParams hash
+  def invoke_params(resource)
+    params = {
+      Name: resource[:dscmeta_resource_friendly_name],
+      Method: resource[:dsc_invoke_method],
+      Property: {}
+    }
+    if resource.key?(:dscmeta_module_version)
+      params[:ModuleName] = {}
+      params[:ModuleName][:ModuleName] = "#{resource[:vendored_modules_path]}/#{resource[:dscmeta_module_name]}/#{resource[:dscmeta_module_name]}.psd1"
+      params[:ModuleName][:RequiredVersion] = resource[:dscmeta_module_version]
+    else
+      params[:ModuleName] = resource[:dscmeta_module_name]
+    end
+    resource[:parameters].each do |property_name, property_hash|
+      # strip dsc_ from the beginning of the property name declaration
+      name = property_name.to_s.gsub(/^dsc_/, '').to_sym
+      params[:Property][name] = if property_hash[:mof_type] == 'PSCredential'
+                                  # format can't unwrap Sensitive strings nested in arbitrary hashes/etc, so make
+                                  # the Credential hash interpolable as it will be replaced by a variable reference.
+                                  {
+                                    'user' => property_hash[:value]['user'],
+                                    'password' => escape_quotes(property_hash[:value]['password'].unwrap)
+                                  }
+                                else
+                                  property_hash[:value]
+                                end
+    end
+    params_block = interpolate_variables("$InvokeParams = #{format(params)}")
+    # HACK: make CIM instances work:
+    resource[:parameters].select { |_key, hash| hash[:mof_is_embedded] && hash[:mof_type] =~ /\[\]/ }.each do |_property_name, property_hash|
+      formatted_property_hash = interpolate_variables(format(property_hash[:value]))
+      params_block = params_block.gsub(formatted_property_hash, "[CimInstance[]]#{formatted_property_hash}")
+    end
+    params_block
+  end
+
+  # Given a resource definition (as from `should_to_resource`), return a PowerShell script which has
+  # all of the appropriate function and variable definitions, which will call Invoke-DscResource, and
+  # will correct munge the results for returning to Puppet as a JSON object.
+  #
+  # @param resource [Hash] a hash with the information needed to run `Invoke-DscResource`
+  # @return [String] A string representing the PowerShell script which will invoke the DSC Resource.
+  def ps_script_content(resource)
+    template_path = File.expand_path('../', __FILE__)
+    # Defines the helper functions
+    functions     = File.new(template_path + '/invoke_dsc_resource_functions.ps1').read
+    # Defines the response hash and the runtime settings
+    preamble      = File.new(template_path + '/invoke_dsc_resource_preamble.ps1').read
+    # The postscript defines the invocation error and result handling; expects `$InvokeParams` to be defined
+    postscript    = File.new(template_path + '/invoke_dsc_resource_postscript.ps1').read
+    # The blocks define the variables to define for the postscript.
+    credential_block = prepare_credentials(resource)
+    cim_instances_block = prepare_cim_instances(resource)
+    parameters_block = invoke_params(resource)
+    # clean them out of the temporary cache now that they're not needed; failure to do so can goof up future executions in this run
+    clear_instantiated_variables!
+
+    content = [functions, preamble, credential_block, cim_instances_block, parameters_block, postscript].join("\n")
+    content
+  end
+
+  # Convert a Puppet/Ruby value into a PowerShell representation. Requires some slight additional
+  # munging over what is provided in the ruby-pwsh library, as it does not handle unwrapping Sensitive
+  # data types or interpolating Credentials.
+  #
+  # @param value [Object] The object to format into valid PowerShell
+  # @return [String] A string representation of the input value as valid PowerShell
+  def format(value)
+    Pwsh::Util.format_powershell_value(value)
+  rescue RuntimeError => e
+    raise unless e.message =~ /Sensitive \[value redacted\]/
+
+    string = Pwsh::Util.format_powershell_value(unwrap(value))
+    string.gsub(/#PuppetSensitive'}/, "'} # PuppetSensitive")
+  end
+
+  # Unwrap sensitive strings for formatting, even inside an enumerable, appending '#PuppetSensitive'
+  # to the end of the string in preparation for gsub cleanup.
+  #
+  # @param value [Object] The object to unwrap sensitive data inside of
+  # @return [Object] The object with any sensitive strings unwrapped and annotated
+  def unwrap(value)
+    if value.class.name == 'Puppet::Pops::Types::PSensitiveType::Sensitive'
+      "#{value.unwrap}#PuppetSensitive"
+    elsif value.class.name == 'Hash'
+      unwrapped = {}
+      value.each do |k, v|
+        unwrapped[k] = unwrap(v)
+      end
+      unwrapped
+    elsif value.class.name == 'Array'
+      unwrapped = []
+      value.each do |v|
+        unwrapped << unwrap(v)
+      end
+      unwrapped
+    else
+      value
+    end
+  end
+
+  # Escape any nested single quotes in a Sensitive string
+  #
+  # @param text [String] the text to escape
+  # @return [String] the escaped text
+  def escape_quotes(text)
+    text.gsub("'", "''")
+  end
+
+  # While Puppet is aware of Sensitive data types, the PowerShell script is not
+  # and so for debugging purposes must be redacted before being sent to debug
+  # output but must *not* be redacted when sent to the PowerShell code manager.
+  #
+  # @param text [String] the text to redact
+  # @return [String] the redacted text
+  def redact_secrets(text)
+    # Every secret unwrapped in this module will unwrap as "'secret' # PuppetSensitive" and, currently,
+    # no known resources specify a SecureString instead of a PSCredential object. We therefore only
+    # need to redact strings which look like password declarations.
+    modified_text = text.gsub(/(?<=-Password )'.+' # PuppetSensitive/, "'#<Sensitive [value redacted]>'")
+    if modified_text =~ /'.+' # PuppetSensitive/
+      # Something has gone wrong, error loudly?
+    else
+      modified_text
+    end
+  end
+
+  # Instantiate a PowerShell manager via the ruby-pwsh library and use it to invoke PowerShell.
+  # Definiing it here allows re-use of a single instance instead of continually instantiating and
+  # tearing a new instance down for every call.
+  def ps_manager
+    debug_output = Puppet::Util::Log.level == :debug
+    # TODO: Allow you to specify an alternate path, either to pwsh generally or a specific pwsh path.
+    Pwsh::Manager.instance(Pwsh::Manager.powershell_path, Pwsh::Manager.powershell_args, debug: debug_output)
+  end
+end

data/lib/puppet/provider/dsc_base_provider/invoke_dsc_resource_functions.ps1

@@ -0,0 +1,120 @@
+function new-pscredential {
+    [CmdletBinding()]
+    param (
+        [parameter(Mandatory = $true,
+            ValueFromPipelineByPropertyName = $true)]
+        [string]
+        $user,
+
+        [parameter(Mandatory = $true,
+            ValueFromPipelineByPropertyName = $true)]
+        [string]
+        $password
+    )
+
+    $secpasswd = ConvertTo-SecureString $password -AsPlainText -Force
+    $credentials = New-Object System.Management.Automation.PSCredential ($user, $secpasswd)
+    return $credentials
+}
+
+Function ConvertTo-CanonicalResult {
+  [CmdletBinding()]
+  param(
+      [Parameter(Mandatory, Position = 1)]
+      [psobject]
+      $Result,
+
+      [Parameter(DontShow)]
+      [string]
+      $PropertyPath,
+
+      [Parameter(DontShow)]
+      [int]
+      $RecursionLevel = 0
+  )
+
+  $MaxDepth = 5
+  $CimInstancePropertyFilter = { $_.Definition -match 'CimInstance' -and $_.Name -ne 'PSDscRunAsCredential' }
+
+  # Get the properties which are/aren't Cim instances
+  $ResultObject = @{ }
+  $ResultPropertyList = $Result | Get-Member -MemberType Property | Where-Object { $_.Name -ne 'PSComputerName' }
+  $CimInstanceProperties = $ResultPropertyList | Where-Object -FilterScript $CimInstancePropertyFilter
+
+  foreach ($Property in $ResultPropertyList) {
+      $PropertyName = $Property.Name
+      if ($Property -notin $CimInstanceProperties) {
+          $Value = $Result.$PropertyName
+          if ($PropertyName -eq 'Ensure' -and [string]::IsNullOrEmpty($Result.$PropertyName)) {
+              # Just set 'Present' since it was found /shrug
+              # If the value IS listed as absent, don't update it unless you want flapping
+              $Value = 'Present'
+          }
+          else {
+              if ($Value -is [string] -or $value -is [string[]]) {
+                  $Value = $Value
+              }
+
+              if ($Value.Count -eq 1 -and $Property.Definition -match '\\[\\]') {
+                  $Value = @($Value)
+              }
+          }
+      }
+      elseif ($null -eq $Result.$PropertyName) {
+          if ($Property -match 'InstanceArray') {
+              $Value = @()
+          }
+          else {
+              $Value = $null
+          }
+      }
+      else {
+          # Looks like a nested CIM instance, recurse if we're not too deep in already.
+          $RecursionLevel++
+
+          if ($PropertyPath -eq [string]::Empty) {
+              $PropertyPath = $PropertyName
+          }
+          else {
+              $PropertyPath = "$PropertyPath.$PropertyName"
+          }
+
+          if ($RecursionLevel -gt $MaxDepth) {
+              # Give up recursing more than this
+              return $Result.ToString()
+          }
+
+          $Value = foreach ($item in $Result.$PropertyName) {
+              ConvertTo-CanonicalResult -Result $item -PropertyPath $PropertyPath -RecursionLevel ($RecursionLevel + 1) -WarningAction Continue
+          }
+
+          # The cim instance type is the last component of the type Name
+          # We need to return this for ruby to compare the result hashes
+          # We do NOT need it for the top-level properties as those are defined in the type
+          If ($RecursionLevel -gt 1 -and ![string]::IsNullOrEmpty($Value) ) {
+              # If there's multiple instances, you need to add the type to each one, but you
+              # need to specify only *one* name, otherwise things end up *very* broken.
+              if ($Value.GetType().Name -match '\[\]') {
+                  $Value | ForEach-Object -Process {
+                      $_.cim_instance_type = $Result.$PropertyName.CimClass.CimClassName[0]
+                  }
+              } else {
+                  $Value.cim_instance_type = $Result.$PropertyName.CimClass.CimClassName
+                  # Ensure that, if it should be an array, it is
+                  if ($Result.$PropertyName.GetType().Name -match '\[\]') {
+                      $Value = @($Value)
+                  }
+              }
+          }
+      }
+
+      if ($Property.Definition -match 'InstanceArray') {
+          if ($Value.Count -lt 2) { $Value = @($Value) }
+      }
+
+      $ResultObject.$PropertyName = $Value
+  }
+
+  # Output the final result
+  $ResultObject
+}

data/lib/puppet/provider/dsc_base_provider/invoke_dsc_resource_postscript.ps1

@@ -0,0 +1,23 @@
+Try {
+  $Result = Invoke-DscResource @InvokeParams
+} catch {
+  $Response.errormessage   = $_.Exception.Message
+  return ($Response | ConvertTo-Json -Compress)
+}
+
+# keep the switch for when Test passes back changed properties
+Switch ($invokeParams.Method) {
+  'Test' {
+    $Response.indesiredstate = $Result.InDesiredState
+    return ($Response | ConvertTo-Json -Compress)
+  }
+  'Set' {
+    $Response.indesiredstate = $true
+    $Response.rebootrequired = $Result.RebootRequired
+    return ($Response | ConvertTo-Json -Compress)
+  }
+  'Get' {
+    $CanonicalizedResult = ConvertTo-CanonicalResult -Result $Result
+    return ($CanonicalizedResult | ConvertTo-Json -Compress -Depth 10)
+  }
+}

data/lib/puppet/provider/dsc_base_provider/invoke_dsc_resource_preamble.ps1

@@ -0,0 +1,8 @@
+$script:ErrorActionPreference = 'Stop'
+$script:WarningPreference = 'SilentlyContinue'
+
+$response = @{
+    indesiredstate = $false
+    rebootrequired = $false
+    errormessage   = ''
+}

data/lib/pwsh.rb

@@ -471,7 +471,7 @@ Invoke-PowerShellUserCode @params
     # @return [String] The UTF-8 encoded string containing the payload
     def self.read_length_prefixed_string!(bytes)
       # 32 bit integer in Little Endian format
-      length = bytes.slice!(0, 4).unpack('V').first
+      length = bytes.slice!(0, 4).unpack1('V')
       return nil if length.zero?
 
       bytes.slice!(0, length).force_encoding(Encoding::UTF_8)
@@ -586,7 +586,7 @@ Invoke-PowerShellUserCode @params
 
       pipe_reader = Thread.new(@pipe) do |pipe|
         # Read a Little Endian 32-bit integer for length of response
-        expected_response_length = pipe.sysread(4).unpack('V').first
+        expected_response_length = pipe.sysread(4).unpack1('V')
 
         next nil if expected_response_length.zero?
 

data/lib/pwsh/util.rb

@@ -12,7 +12,7 @@ module Pwsh
     def on_windows?
       # Ruby only sets File::ALT_SEPARATOR on Windows and the Ruby standard
       # library uses that to test what platform it's on.
-      !!File::ALT_SEPARATOR # rubocop:disable Style/DoubleNegation
+      !!File::ALT_SEPARATOR
     end
 
     # Verify paths specified are valid directories which exist.

data/lib/pwsh/version.rb

@@ -2,5 +2,5 @@
 
 module Pwsh
   # The version of the ruby-pwsh gem
-  VERSION = '0.4.1'
+  VERSION = '0.5.0'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: ruby-pwsh
 version: !ruby/object:Gem::Version
-  version: 0.4.1
+  version: 0.5.0
 platform: ruby
 authors:
 - Puppet, Inc.
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2020-02-13 00:00:00.000000000 Z
+date: 2020-08-20 00:00:00.000000000 Z
 dependencies: []
 description: PowerShell code manager for ruby.
 email:
@@ -31,8 +31,13 @@ files:
 - LICENSE.txt
 - README.md
 - Rakefile
+- appveyor.yml
 - design-comms.png
 - lib/puppet/feature/pwshlib.rb
+- lib/puppet/provider/dsc_base_provider/dsc_base_provider.rb
+- lib/puppet/provider/dsc_base_provider/invoke_dsc_resource_functions.ps1
+- lib/puppet/provider/dsc_base_provider/invoke_dsc_resource_postscript.ps1
+- lib/puppet/provider/dsc_base_provider/invoke_dsc_resource_preamble.ps1
 - lib/pwsh.rb
 - lib/pwsh/util.rb
 - lib/pwsh/version.rb