cem_acpt 0.11.0 → 0.11.2

data/specifications/CEM-6719.md

@@ -0,0 +1,173 @@
+# CEM-6719: Remove unreferenced top-level helpers and Windows placeholder
+
+Implements [RFC 0010](../docs/rfcs/0010-dead-code-cleanup.md).
+
+## Summary
+
+Delete dead code surfaced by the architecture audit (`docs/ARCHITECTURE.md` §19,
+items 1–3) and refresh the doc to drop the items being removed:
+
+1. `lib/cem_acpt/puppet_helpers.rb` — superseded by `Utils::Puppet::ModulePackageBuilder`.
+2. `lib/cem_acpt/action_result.rb` — superseded by `TestRunner::TestResults::TestActionResult` /
+   `TestErrorActionResult`. Defines top-level `CemAcpt::ActionResult` /
+   `CemAcpt::ErrorActionResult` constants that shadow more useful names.
+3. `Provision::Windows#provision_commands` returning `['placeholder']` — inert
+   on the Windows path, which has no Terraform `remote-exec`.
+4. `Utils.package_win_module` — unused; confirmed via `git grep` (no callers
+   outside its own definition + docs).
+
+## Audit results
+
+`git grep` performed against `lib/`, `exe/`, and `spec/`:
+
+| Symbol                                             | Hits outside its own file / docs |
+|----------------------------------------------------|----------------------------------|
+| `PuppetHelpers`                                    | none                             |
+| `puppet_helpers`                                   | none (no `require_relative`s)    |
+| `CemAcpt::ActionResult` / `CemAcpt::ErrorActionResult` | none — `TestErrorActionResult` is a different class under `TestRunner::TestResults` |
+| `action_result` (require)                          | none                             |
+| `package_win_module`                               | none                             |
+| `Provision::Windows#provision_commands`            | called from `lib/cem_acpt/provision/terraform.rb:276` (handled below) |
+
+## Functional behavior
+
+### 1. Delete `lib/cem_acpt/puppet_helpers.rb`
+
+- Remove the file outright. Nothing requires it.
+- No code-level changes elsewhere needed.
+
+### 2. Delete `lib/cem_acpt/action_result.rb`
+
+- Remove the file outright. Nothing requires it.
+- The runner uses the namespaced `CemAcpt::TestRunner::TestResults::TestActionResult`
+  / `TestErrorActionResult` — these stay.
+
+### 3. Remove `Provision::Windows#provision_commands` placeholder
+
+The base class `OsData#provision_commands` already raises `NotImplementedError`
+(`lib/cem_acpt/provision/terraform/os_data.rb:117`). The Windows subclass
+override at `lib/cem_acpt/provision/terraform/windows.rb:26-28` exists only to
+satisfy the call at `lib/cem_acpt/provision/terraform.rb:276`, where the
+Windows path threads `provision_commands` into the JSON `node_data` even
+though the Windows `main.tf` (`lib/terraform/gcp/windows/main.tf:51-58`) does
+not declare a `provision_commands` field on the `node_data` object type.
+
+Approach:
+
+- Replace the override with a method that raises `NotImplementedError` with a
+  descriptive message pointing at `Utils::WinRMRunner` and `ARCHITECTURE.md` §13:
+  ```ruby
+  def provision_commands
+    raise NotImplementedError,
+          'Windows provisioning is performed via Utils::WinRMRunner, not via ' \
+          'Terraform remote-exec. See ARCHITECTURE.md §13.'
+  end
+  ```
+- Update `lib/cem_acpt/provision/terraform.rb:268-283` so the Windows backend
+  no longer triggers the call. Use a `case` on backend class:
+  ```ruby
+  provision_commands: case @backend
+                      when CemAcpt::Provision::Linux
+                        @backend.provision_commands_wrapper(node.node_data[:image])
+                      when CemAcpt::Provision::Windows
+                        []
+                      else
+                        @backend.provision_commands
+                      end
+  ```
+  Passing `[]` (instead of dropping the key) keeps the merged-hash shape
+  identical to today (where `['placeholder']` is currently passed) — Terraform
+  silently ignores unknown attributes on the Windows `node_data` type.
+- Net effect: the override now raises with a clear message if a future
+  contributor calls it, and the call site stops invoking it for Windows.
+
+### 4. Delete `Utils.package_win_module`
+
+- Remove `lib/cem_acpt/utils.rb:17-26`. The `class << self ... include
+  CemAcpt::Logging ... end` block stays — `reset_password_readiness_polling`
+  / `get_windows_login_info` still need the `logger` accessor.
+- The `require 'fileutils'` was implicitly relied on by `package_win_module`'s
+  `FileUtils.rm_f`; the remaining methods don't use FileUtils, so no require
+  needs to be added.
+
+### 5. Update `docs/ARCHITECTURE.md`
+
+- §19: delete items 1, 2, 3 (the items resolved by this ticket). Renumber the
+  remaining items (4 → 1, 5 → 2, 6 → 3, 7 → 4) and update internal references
+  accordingly.
+- File-tree (lines 70, 79): remove the `action_result.rb` and
+  `puppet_helpers.rb` entries.
+- §14 (line 871): drop "unused `package_win_module`" from the parenthetical
+  describing `lib/cem_acpt/utils.rb`.
+- §7 (lines 491-493): rephrase the "`Provision::Windows#provision_commands`
+  returns `['placeholder']`" note to reflect that the Windows backend no
+  longer threads commands through Terraform at all (call site dispatches on
+  backend class; method now raises).
+
+## Inputs / outputs / contracts
+
+- No public-API surface change (these symbols are internal helpers with no
+  external callers).
+- `Provision::Terraform#provision_node_data` continues to produce the same
+  JSON shape — for Windows, `provision_commands` becomes `[]` instead of
+  `['placeholder']`.
+
+## Edge cases
+
+- A future contributor invokes `Provision::Windows.new(...).provision_commands`
+  directly: now raises a descriptive `NotImplementedError` instead of returning
+  silently-misleading `['placeholder']`.
+- Anything that `require`'d `cem_acpt/puppet_helpers` or `cem_acpt/action_result`
+  externally would break — but `git grep` confirms no such consumer exists in
+  the repo, and these are internal (the gem's lib root does not auto-require
+  them).
+
+## Constraints / invariants
+
+- RuboCop must remain clean (200-char line limit, the existing permissive
+  `.rubocop.yml`).
+- `bundle exec rake spec` must pass.
+- The Windows test-node provisioning flow continues to work: Terraform
+  applies, then `Utils::WinRMRunner` does the real work.
+
+## Error handling
+
+- Removing `puppet_helpers.rb` / `action_result.rb`: file deletions, nothing
+  to handle.
+- The new `NotImplementedError` message in `Provision::Windows#provision_commands`
+  is descriptive and points at the relevant subsystem.
+
+## Non-goals
+
+- Filling in `lib/terraform/image/gcp/windows/` (RFC 0003, §19 item 7).
+- Wiring up `BoltOutputFormatter` / `BoltErrorFormatter` (§19 item 6).
+- Making the `provisioner` static-option configurable (§19 item 4).
+- Any other §19 item beyond 1, 2, 3.
+
+## Acceptance criteria
+
+- [ ] `lib/cem_acpt/puppet_helpers.rb` deleted; `git grep PuppetHelpers
+      lib/ exe/ spec/` returns no matches.
+- [ ] `lib/cem_acpt/action_result.rb` deleted; `git grep CemAcpt::ActionResult
+      lib/ exe/ spec/` returns no matches.
+- [ ] `Provision::Windows#provision_commands` no longer returns
+      `['placeholder']`; raises `NotImplementedError` with a descriptive
+      message instead.
+- [ ] `Provision::Terraform#provision_node_data` does not call
+      `provision_commands` on a Windows backend.
+- [ ] `Utils.package_win_module` removed.
+- [ ] `docs/ARCHITECTURE.md` §19 items 1, 2, 3 removed; remaining items
+      renumbered; file-tree and §14 references to deleted symbols cleaned up;
+      §7 Windows note updated.
+- [ ] `bundle exec rake spec` passes.
+- [ ] `rubocop` is clean against the changed files.
+
+## Test plan
+
+- Existing specs cover `Utils::Puppet::ModulePackageBuilder` (the live
+  replacement for the deleted `PuppetHelpers::Module`) and
+  `TestRunner::TestResults` (the live replacement for the deleted top-level
+  `ActionResult`). No new unit tests are needed for deletions of unused code.
+- Add a small spec for `Provision::Windows#provision_commands` confirming it
+  raises `NotImplementedError` with the expected message — locks in the new
+  behavior so a future contributor doesn't reintroduce a placeholder.

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: cem_acpt
 version: !ruby/object:Gem::Version
-  version: 0.11.0
+  version: 0.11.2
 platform: ruby
 authors:
 - puppetlabs
-autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-03-30 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: async-http
@@ -223,11 +222,11 @@ executables:
 extensions: []
 extra_rdoc_files: []
 files:
-- ".claude/settings.local.json"
 - ".github/workflows/spec.yml"
 - ".gitignore"
 - ".rspec"
 - ".rubocop.yml"
+- ".worktreeinclude"
 - CLAUDE.md
 - CODEOWNERS
 - Gemfile
@@ -237,10 +236,23 @@ files:
 - bin/console
 - bin/setup
 - cem_acpt.gemspec
+- docs/ARCHITECTURE.md
+- docs/rfcs/0000-template.md
+- docs/rfcs/0001-fix-bolt-missing-skip-path.md
+- docs/rfcs/0002-fix-default-character-substitutions.md
+- docs/rfcs/0003-windows-image-builder-template.md
+- docs/rfcs/0004-image-name-truncation-off-by-one.md
+- docs/rfcs/0005-os-dispatch-replace-windows-heuristic.md
+- docs/rfcs/0006-configurable-windows-bucket.md
+- docs/rfcs/0007-logging-quiet-and-typos.md
+- docs/rfcs/0008-namespace-platform-classes.md
+- docs/rfcs/0009-bolt-log-formatter-cleanup.md
+- docs/rfcs/0010-dead-code-cleanup.md
+- docs/rfcs/0011-provisioner-factory-consistency.md
+- docs/rfcs/README.md
 - exe/cem_acpt
 - exe/cem_acpt_image
 - lib/cem_acpt.rb
-- lib/cem_acpt/action_result.rb
 - lib/cem_acpt/actions.rb
 - lib/cem_acpt/bolt.rb
 - lib/cem_acpt/bolt/cmd.rb
@@ -265,6 +277,7 @@ files:
 - lib/cem_acpt/goss/api.rb
 - lib/cem_acpt/goss/api/action_response.rb
 - lib/cem_acpt/image_builder.rb
+- lib/cem_acpt/image_builder/errors.rb
 - lib/cem_acpt/image_builder/exec.rb
 - lib/cem_acpt/image_builder/provision_commands.rb
 - lib/cem_acpt/image_name_builder.rb
@@ -279,13 +292,10 @@ files:
 - lib/cem_acpt/provision/terraform/os_data.rb
 - lib/cem_acpt/provision/terraform/terraform_cmd.rb
 - lib/cem_acpt/provision/terraform/windows.rb
-- lib/cem_acpt/puppet_helpers.rb
 - lib/cem_acpt/test_data.rb
 - lib/cem_acpt/test_runner.rb
 - lib/cem_acpt/test_runner/log_formatter.rb
 - lib/cem_acpt/test_runner/log_formatter/base.rb
-- lib/cem_acpt/test_runner/log_formatter/bolt_error_formatter.rb
-- lib/cem_acpt/test_runner/log_formatter/bolt_output_formatter.rb
 - lib/cem_acpt/test_runner/log_formatter/bolt_summary_results_formatter.rb
 - lib/cem_acpt/test_runner/log_formatter/goss_action_response.rb
 - lib/cem_acpt/test_runner/log_formatter/goss_error_formatter.rb
@@ -314,6 +324,13 @@ files:
 - lib/terraform/image/gcp/linux/main.tf
 - lib/terraform/image/gcp/windows/.keep
 - sample_config.yaml
+- specifications/CEM-6713.md
+- specifications/CEM-6714.md
+- specifications/CEM-6715.md
+- specifications/CEM-6716.md
+- specifications/CEM-6717.md
+- specifications/CEM-6718.md
+- specifications/CEM-6719.md
 homepage: https://github.com/puppetlabs/cem_acpt
 licenses:
 - proprietary
@@ -321,7 +338,6 @@ metadata:
   homepage_uri: https://github.com/puppetlabs/cem_acpt
   source_code_uri: https://github.com/puppetlabs/cem_acpt
   changelog_uri: https://github.com/puppetlabs/cem_acpt
-post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -336,8 +352,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.18
-signing_key:
+rubygems_version: 3.6.9
 specification_version: 4
 summary: CEM Acceptance Tests
 test_files: []

data/.claude/settings.local.json

@@ -1,7 +0,0 @@
-{
-  "permissions": {
-    "allow": [
-      "Bash(xargs ls:*)"
-    ]
-  }
-}

data/lib/cem_acpt/action_result.rb

@@ -1,91 +0,0 @@
-# frozen_string_literal: true
-
-module CemAcpt
-  # Wrapper class for the result of an action. Provides a common interface for
-  # getting reportable data from the result.
-  class ActionResult
-    attr_reader :result
-
-    def initialize(result)
-      @result = if result.instance_of?(CemAcpt::Goss::Api::ActionResponse)
-                  result
-                elsif result.instance_of?(CemAcpt::Bolt::Cmd::Output)
-                  result
-                elsif result.is_a?(StandardError)
-                  ErrorActionResult.new(result)
-                else
-                  raise ArgumentError, "result must be a CemAcpt::Goss::Api::ActionResponse, CemAcpt::Bolt::Cmd::Output, or StandardError, got #{result.class}"
-                end
-    end
-
-    def error?
-      @result.is_a?(ErrorActionResult) || (@result.respond_to?(:error?) && @result.error?)
-    end
-
-    def method_missing(method_name, *args, **kwargs, &block)
-      if @result.respond_to?(method_name)
-        @result.send(method_name, *args, **kwargs, &block)
-      else
-        super
-      end
-    end
-
-    def respond_to_missing?(method_name, include_private = false)
-      @result.respond_to?(method_name, include_private) || super
-    end
-  end
-
-  # Wrapper class for an error raised during an action.
-  class ErrorActionResult
-    attr_reader :error
-
-    def initialize(error)
-      @error = error
-    end
-
-    def error?
-      true
-    end
-
-    def success?
-      false
-    end
-
-    def to_s
-      "#<#{@error.class.name}:0x#{@error.object_id.to_s(16)}>"
-    end
-
-    def inspect
-      to_s
-    end
-
-    def to_h
-      {
-        class: @error.class.name,
-        message: @error.message,
-        backtrace: @error.backtrace,
-      }
-    end
-
-    def status
-      1
-    end
-    alias http_status status
-
-    def results
-      @error.backtrace
-    end
-
-    def results?
-      true
-    end
-
-    def summary
-      @error.message
-    end
-
-    def summary?
-      true
-    end
-  end
-end

data/lib/cem_acpt/puppet_helpers.rb

@@ -1,38 +0,0 @@
-# frozen_string_literal: true
-
-require_relative 'logging'
-
-module CemAcpt
-  # Holds modules that provide helper methods for various Puppet-related
-  # tasks.
-  module PuppetHelpers
-    # Provides helper methods for Puppet Modules.
-    module Module
-      class << self
-        include CemAcpt::Logging
-      end
-
-      # Builds a Puppet module package.
-      # @param module_dir [String] Path to the module directory. If target_dir
-      #   is specified as a relative path, it will be relative to the module dir.
-      # @param target_dir [String] Path to the target directory where the package
-      #   will be built. This defaults to the relative path 'pkg/'.
-      # @param should_log [Boolean] Whether or not to log the build process.
-      # @return [String] Path to the built package.
-      def self.build_module_package(module_dir, target_dir = nil, should_log: false)
-        require 'puppet/modulebuilder'
-        require 'fileutils'
-
-        builder_logger = should_log ? logger : nil
-        builder = Puppet::Modulebuilder::Builder.new(File.expand_path(module_dir), target_dir, builder_logger)
-
-        # Validates module metadata by raising exception if invalid
-        _metadata = builder.metadata
-
-        # Builds the module package
-        logger.info('CemAcpt::PuppetHelpers') { "Building module package for #{builder.release_name}" }
-        builder.build
-      end
-    end
-  end
-end

data/lib/cem_acpt/test_runner/log_formatter/bolt_error_formatter.rb

@@ -1,65 +0,0 @@
-# frozen_string_literal: true
-
-require_relative 'base'
-
-module CemAcpt
-  module TestRunner
-    module LogFormatter
-      class BoltErrorFormatter < Base
-        def initialize(subject: nil)
-          super(subject)
-        end
-
-        def summary(response = nil)
-          super(response)
-          "Error: #{log_subject.summary}"
-        end
-
-        def results(response = nil)
-          super(response)
-          log_subject.results.map do |res|
-            format_failed_result(res)
-          end
-        end
-
-        def host_name(response = nil)
-          super(response)
-          "Error: #{log_subject.error.class.name}"
-        end
-
-        def test_name(response = nil)
-          super(response)
-          "Error: #{log_subject.error.class.name}"
-        end
-
-        private
-
-        def format_failed_result(res)
-          prefix = [
-            'Failed',
-            "action #{res.action}",
-            "object #{res.object}",
-            "target #{res.target}",
-          ].join(': ')
-          return prefix unless res.error?
-
-          error_parts = [
-            "error type #{res.error.class.name}",
-            normalize_whitespace(res.error.to_s),
-          ]
-          if res.error.respond_to?(:details) && res.error.details
-            error_parts << "details #{res.error.details}"
-          end
-          if res.error.respond_to?(:original_error) && res.error.original_error
-            error_parts << "original error #{res.error.original_error.class.name}"
-            error_parts << "original message #{res.error.original_error.message}"
-          end
-          if res.error.respond_to?(:backtrace) && !res.error.backtrace.empty?
-            error_parts << "backtrace:\n#{res.error.backtrace.join("\n#{INDENT}#{INDENT}")}"
-          end
-          "#{prefix}\n#{INDENT}#{error_parts.join("\n#{INDENT}")}"
-        end
-      end
-    end
-  end
-end

data/lib/cem_acpt/test_runner/log_formatter/bolt_output_formatter.rb

@@ -1,54 +0,0 @@
-# frozen_string_literal: true
-
-require_relative 'base'
-
-module CemAcpt
-  module TestRunner
-    module LogFormatter
-      # Formats the results of a Bolt action
-      class BoltOutputFormatter < Base
-        def initialize(config, instance_names_ips, subject: nil)
-          super(subject)
-          @config = config
-          @instance_names_ips = instance_names_ips
-        end
-
-        def summary(response = nil)
-          super(response)
-          [
-            "SUMMARY: #{test_name(log_subject)}:",
-            normalize_whitespace(log_subject.summary),
-          ].join(' ')
-        end
-
-        def results(response = nil)
-          super(response)
-          log_subject.results.map do |res|
-            prefix = success_str(res.success?).capitalize
-            parts = [
-              prefix,
-              "action #{res.action}",
-              "host(s) #{host_name(log_subject)}",
-              "object #{res.object}",
-              "status #{res.status}",
-            ]
-            parts << res.error if res.error?
-            parts.join(': ')
-          end
-        end
-
-        def host_name(response = nil)
-          super(response)
-          log_subject.items.map { |i| name_from_ip(i.target) }.compact.uniq.join(', ')
-        end
-
-        def test_name(response = nil)
-          super(response)
-          test_type = (log_subject.items.find { |i| i.action != 'unknown' }&.action || 'unknown')
-          test_objects = log_subject.items.map(&:object).uniq.join(', ')
-          "Bolt #{test_type} test for: #{test_objects}"
-        end
-      end
-    end
-  end
-end