cem_acpt 0.11.0 → 0.11.2

data/docs/rfcs/0000-template.md

@@ -0,0 +1,54 @@
+# RFC NNNN: Title
+
+- **Status:** Proposed | Accepted | Rejected | Implemented | Withdrawn
+- **Author:** TBD
+- **Created:** YYYY-MM-DD
+- **Priority:** Critical | High | Medium | Low
+- **Category:** Bug | Refactor | Feature | Cleanup
+- **Affected components:** `lib/...`
+
+## Summary
+
+One paragraph describing the change at a glance. A reader who only reads
+this section should walk away knowing what is being proposed and why.
+
+## Background
+
+The relevant context: how the affected code works today, where it lives,
+and which sections of [`docs/ARCHITECTURE.md`](../ARCHITECTURE.md) describe
+it. Cite specific files and line numbers where helpful.
+
+## Problem
+
+State the problem precisely. Include reproduction steps, error messages,
+or pointers to the offending lines of code. Be explicit about the user-
+visible symptom (e.g. "crashes with `NoMethodError`", "silently produces
+wrong output", "is dead code that confuses contributors").
+
+## Proposal
+
+Describe the proposed change. Use code snippets, function signatures,
+or before/after diffs where they clarify the intent. If multiple files
+need to change, list them.
+
+## Alternatives Considered
+
+Other ways to solve the problem and why they were not chosen.
+
+## Risks & Migration
+
+- Backwards-compatibility implications.
+- Whether the change is user-visible (CLI, config schema, exit codes,
+  log output) and whether existing configs continue to work.
+- Required follow-ups in the consuming Puppet modules (`sce_linux`,
+  `sce_windows`, etc.) if any.
+
+## Acceptance Criteria
+
+A checklist a reviewer can run through to confirm the RFC has been
+implemented:
+
+- [ ] Code change merged.
+- [ ] RSpec coverage added or updated.
+- [ ] `docs/ARCHITECTURE.md` updated if architecture-level facts change.
+- [ ] CHANGELOG / version bump (if user-visible).

data/docs/rfcs/0001-fix-bolt-missing-skip-path.md

@@ -0,0 +1,105 @@
+# RFC 0001: Fix the bolt-missing skip path
+
+- **Status:** Implemented
+- **Author:** Heston Snodgrass
+- **Created:** 2026-04-30
+- **Implemented:** 2026-05-01 (CEM-6710, PR #71)
+- **Priority:** Critical
+- **Category:** Bug
+- **Affected components:** `lib/cem_acpt/test_runner.rb`, `lib/cem_acpt/actions.rb`
+
+## Summary
+
+When the `bolt` binary is not on the user's PATH the runner is supposed
+to gracefully skip the `:bolt` action group. The current rescue path
+calls two methods that do not exist on the relevant objects, so instead
+of skipping it raises `NoMethodError` and aborts the entire test run
+before any nodes are provisioned.
+
+## Background
+
+`Runner#setup_bolt` (`lib/cem_acpt/test_runner.rb:200-218`) constructs
+`Bolt::TestRunner` and calls `setup!`, which in turn shells out to
+`bolt task show`. If the binary is missing, `Utils::Shell.run_cmd`
+raises `CemAcpt::ShellCommandNotFoundError`. The current rescue is:
+
+```ruby
+rescue CemAcpt::ShellCommandNotFoundError => e
+  logger.warning('CemAcpt::TestRunner') { e.message }
+  logger.warning('CemAcpt::TestRunner') { 'Adding Bolt action to ignore list...' }
+  CemAcpt::Actions.config.ignore << :bolt
+  return
+end
+```
+
+[`docs/ARCHITECTURE.md` §8 and §19 (item 7)](../ARCHITECTURE.md#19-open-questions--observed-dead-code)
+already flag this path as broken.
+
+## Problem
+
+Two defects in three lines:
+
+1. **`logger.warning` is not defined.** `CemAcpt::Logging::Logger`
+   defines `warn` (`lib/cem_acpt/logging.rb:116`), inherited from
+   `::Logger`. Calling `warning` raises `NoMethodError` immediately.
+2. **`CemAcpt::Actions.config.ignore` is not defined.** `ActionConfig`
+   exposes only `groups`, `only`, and `except`
+   (`lib/cem_acpt/actions.rb:67-118`). Even after fixing the typo at
+   #1, this line raises a second `NoMethodError`.
+
+The rescue therefore never completes successfully. A user without
+`bolt` installed cannot run `cem_acpt` at all, despite the README and
+ARCHITECTURE doc both describing the behavior as graceful.
+
+## Proposal
+
+Use the existing `except` mechanism, which already filters actions in
+`ActionGroup#filter_actions` (`lib/cem_acpt/actions.rb:52-60`):
+
+```ruby
+rescue CemAcpt::ShellCommandNotFoundError => e
+  logger.warn('CemAcpt::TestRunner') { e.message }
+  logger.warn('CemAcpt::TestRunner') { 'Bolt binary not found on PATH; skipping :bolt action.' }
+  CemAcpt::Actions.config.except = (CemAcpt::Actions.config.except + [:bolt]).uniq
+  return
+end
+```
+
+Notes:
+
+- `except=` is the public setter; using it preserves the
+  `ArgumentError` guard on non-Array inputs.
+- Going via `(except + [:bolt]).uniq` keeps any user-supplied
+  `--except-actions` entries intact.
+- Switch both `logger.warning` calls to `logger.warn`.
+
+Alternatively, if "ignore" is preferred semantically, add an `ignore`
+accessor to `ActionConfig` and have `filter_actions` honor it. This is
+a larger surface change for no behavioral benefit over `except`.
+
+## Alternatives Considered
+
+- **Add a dedicated `ActionConfig#ignore` accessor.** Spelling matches
+  the original intent in the rescue but introduces a third filter list
+  with semantics identical to `except`.
+- **Probe `bolt` up front in `Cli`/`Config` and short-circuit there.**
+  Cleaner separation but moves the policy decision away from the place
+  that actually decides to register the action group. Defer.
+
+## Risks & Migration
+
+- No config change. No CLI surface change.
+- Users who currently work around the bug by always having `bolt`
+  installed are unaffected. Users who hit it today hit a hard crash;
+  after the change they get a `WARN` log and the test run continues
+  with the `:goss` group only.
+
+## Acceptance Criteria
+
+- [x] `lib/cem_acpt/test_runner.rb:206-208` updated as above.
+- [x] RSpec test added to `spec/cem_acpt/test_runner_spec.rb` that
+      stubs `Bolt::TestRunner#setup!` to raise
+      `ShellCommandNotFoundError` and asserts the run continues with
+      `:bolt` filtered out of the registered action groups.
+- [ ] Manual smoke test on a host without `bolt` installed: full run
+      completes with exit code reflecting only Goss results.

data/docs/rfcs/0002-fix-default-character-substitutions.md

@@ -0,0 +1,119 @@
+# RFC 0002: Fix malformed default `image_name_builder.character_substitutions`
+
+- **Status:** Implemented
+- **Author:** Heston Snodgrass
+- **Created:** 2026-04-30
+- **Implemented:** 2026-05-01 (CEM-6711, [PR #72](https://github.com/puppetlabs/cem_acpt/pull/72))
+- **Priority:** Critical
+- **Category:** Bug
+- **Affected components:** `lib/cem_acpt/config/cem_acpt.rb`, `lib/cem_acpt/image_name_builder.rb`
+
+## Summary
+
+The default value for `image_name_builder.character_substitutions` in
+`Config::CemAcpt::DEFAULTS` is a single 2-item array, but
+`ImageNameBuilder#character_substitutions` expects an *array of*
+2-item arrays. Iterating the default produces `nil` second arguments
+to `String#gsub!`, which raises `TypeError` and aborts the run.
+
+## Background
+
+`Config::CemAcpt#defaults` (`lib/cem_acpt/config/cem_acpt.rb:30-34`):
+
+```ruby
+image_name_builder: {
+  character_substitutions: ['_', '-'],
+  parts: ['cem-acpt', '$image_fam', '$collection', '$firewall'],
+  join_with: '-',
+},
+```
+
+`ImageNameBuilder#character_substitutions`
+(`lib/cem_acpt/image_name_builder.rb:85-93`):
+
+```ruby
+def character_substitutions(name)
+  return name unless @config[:character_substitutions]
+
+  subbed_name = name
+  @config[:character_substitutions].each do |char_sub|
+    subbed_name.gsub!(char_sub[0], char_sub[1])
+  end
+  subbed_name
+end
+```
+
+The class-level docstring (line 16) and `sample_config.yaml` both
+describe the value as "An array of 2-item arrays" (e.g.
+`[['_', '-'], ['.', '-']]`). [`docs/ARCHITECTURE.md` §19 (item 10)](../ARCHITECTURE.md#19-open-questions--observed-dead-code)
+flags this as a default-vs-shape mismatch.
+
+## Problem
+
+With the default config:
+
+```ruby
+config[:image_name_builder][:character_substitutions]  # => ['_', '-']
+.each do |char_sub|
+  # iter 1: char_sub == '_', char_sub[0] == '_', char_sub[1] == nil
+  subbed_name.gsub!('_', nil)  # => TypeError: no implicit conversion of nil into String
+end
+```
+
+The bug is masked because most users override `image_name_builder` with
+the documented nested form. Anyone relying on defaults — including a
+fresh contributor running `cem_acpt -Y` and then a real run — hits the
+crash.
+
+## Proposal
+
+Change the default to the documented nested shape:
+
+```ruby
+image_name_builder: {
+  character_substitutions: [['_', '-']],
+  ...
+}
+```
+
+Additionally, add a defensive shape check in `ImageNameBuilder` so a
+future malformed override fails fast with a clear message instead of
+the same `TypeError`:
+
+```ruby
+def character_substitutions(name)
+  return name unless @config[:character_substitutions]
+
+  subs = Array(@config[:character_substitutions])
+  unless subs.all? { |s| s.is_a?(Array) && s.size == 2 }
+    raise ArgumentError,
+      'image_name_builder.character_substitutions must be an array of 2-item arrays'
+  end
+  ...
+end
+```
+
+## Alternatives Considered
+
+- **Auto-promote a flat 2-item array to `[['_', '-']]`.** Tempting but
+  ambiguous — `['_', '-', '.', '-']` would be even more confusing.
+- **Drop the default entirely.** Would force everyone to override.
+  The default is genuinely useful (GCP image names disallow `_`); keep
+  it, just spell it correctly.
+
+## Risks & Migration
+
+- Any user who happened to depend on the current (broken) default
+  cannot exist, since the default crashes.
+- A user who has correctly specified the nested form is unaffected by
+  the default change but will get the new validation error if their
+  override is malformed.
+
+## Acceptance Criteria
+
+- [x] Default updated to `[['_', '-']]`.
+- [x] Validation added to `ImageNameBuilder#character_substitutions`.
+- [x] RSpec test confirms a default-config `ImageNameBuilder.build`
+      runs without error.
+- [x] RSpec test confirms a flat 2-item array now raises a clear
+      `ArgumentError` rather than `TypeError`.

data/docs/rfcs/0003-windows-image-builder-template.md

@@ -0,0 +1,110 @@
+# RFC 0003: Ship a Windows image-builder Terraform template (or fail clearly)
+
+- **Status:** Short term implemented (CEM-6712); long term still proposed
+- **Author:** TBD
+- **Created:** 2026-04-30
+- **Updated:** 2026-05-01
+- **Priority:** Critical
+- **Category:** Bug
+- **Affected components:** `lib/terraform/image/gcp/windows/`, `lib/cem_acpt/image_builder.rb`, `lib/cem_acpt/config/cem_acpt_image.rb`
+
+## Summary
+
+`lib/terraform/image/gcp/windows/` currently contains only an empty
+`.keep` file — there is no `main.tf`. The image builder routes any
+Windows entry in `config.images` to this directory and runs
+`terraform init` against it, which fails with a confusing "no
+configuration files" error rather than a meaningful one.
+
+## Background
+
+The image builder has parallel Linux and Windows working trees:
+
+```
+lib/terraform/image/gcp/
+├── linux/      # main.tf, provisioners, etc.
+└── windows/    # only .keep
+```
+
+`ImageBuilder::TerraformBuilder#in_os_dir` (`lib/cem_acpt/image_builder.rb`)
+`Dir.chdir`s to each populated tree and runs the same Terraform CLI
+choreography described in [`docs/ARCHITECTURE.md` §12](../ARCHITECTURE.md#12-cem_acpt_image-image-builder-lifecycle).
+[§19 (item 9)](../ARCHITECTURE.md#19-open-questions--observed-dead-code)
+flags the missing template.
+
+## Problem
+
+There are two distinct user-visible symptoms:
+
+1. A user who configures any Windows image entry (or doesn't pass
+   `--no-windows`) gets a `terraform init` failure with no actionable
+   error message.
+2. There is no signal in the repo that Windows image building is
+   unsupported — the directory and the code path that routes to it
+   both exist.
+
+## Proposal
+
+Two complementary changes.
+
+### Short term: clear, early failure (implemented in CEM-6712)
+
+`ImageBuilder::TerraformBuilder#assert_template_present!` checks for
+`main.tf` under `File.join(@image_terraform_dir, os_str)` and, if it
+is missing, raises `ImageBuilder::MissingTemplateError` (defined in
+`lib/cem_acpt/image_builder/errors.rb`) with a message that names the
+missing path and points to `--no-#{os_str}`.
+
+It is invoked from `run` for every OS bucket in `image_types`,
+*before* the working directory is created and before `terraform init`,
+so the misconfiguration is caught even in `--dry-run` mode.
+
+### Long term: ship the template
+
+Author `lib/terraform/image/gcp/windows/main.tf` modeled on the Linux
+template. The Windows image-build node needs to:
+
+- accept the same vars (`platform_data`, `node_data`, `provision_commands`,
+  `puppet_auth_token`),
+- create a `google_compute_instance` with the appropriate Windows
+  base image and a metadata block enabling WinRM,
+- wait for the instance to come up, then run `provision_commands` over
+  WinRM (the existing `Utils::WinRMRunner` is already set up for this
+  in the test path; the image-build path can reuse the same
+  PowerShell shape).
+
+A separate follow-up RFC may be appropriate for the WinRM-from-Terraform
+choreography, since the current Windows test path runs PowerShell from
+Ruby rather than from Terraform.
+
+## Alternatives Considered
+
+- **Delete `lib/terraform/image/gcp/windows/` and reject Windows
+  entries in config.** Cleaner short term, but kills the option of
+  ever building Windows images.
+- **Lean on packer instead of Terraform for Windows.** A larger
+  architectural change; out of scope here.
+
+## Risks & Migration
+
+- Short-term change is purely additive (a new error message). No
+  existing config breaks.
+- Long-term template is feature work. Should be gated behind tests
+  before being declared supported.
+
+## Acceptance Criteria
+
+Short-term (CEM-6712, complete):
+
+- [x] `ImageBuilder::TerraformBuilder#assert_template_present!` raises
+      `ImageBuilder::MissingTemplateError` if an OS bucket has images
+      configured without a template on disk.
+- [x] `spec/cem_acpt/image_builder_spec.rb` asserts the error message
+      names the missing template path and points to `--no-<os>`.
+
+Long-term (separate PR(s)):
+
+- [ ] `main.tf` exists under `lib/terraform/image/gcp/windows/`.
+- [ ] An end-to-end Windows image build succeeds in CI.
+- [ ] [`docs/ARCHITECTURE.md` §12](../ARCHITECTURE.md#12-cem_acpt_image-image-builder-lifecycle)
+      and §19 are updated.

data/docs/rfcs/0004-image-name-truncation-off-by-one.md

@@ -0,0 +1,108 @@
+# RFC 0004: Fix image-name truncation off-by-one
+
+- **Status:** Implemented
+- **Author:** TBD
+- **Created:** 2026-04-30
+- **Implemented:** 2026-05-04 (CEM-6713)
+- **Priority:** High
+- **Category:** Bug
+- **Affected components:** `lib/cem_acpt/image_builder.rb`
+
+## Summary
+
+`ImageBuilder::TerraformBuilder#image_name_from_image_family` produces
+an image name up to 65 characters long. GCE image names are limited
+to 63 characters (RFC 1035 label rule). The slice was clearly intended
+to enforce the limit but uses an inclusive-range off-by-one and the
+wrong cap. As written it neither enforces 63 nor 64 and can silently
+produce names that GCE rejects.
+
+## Background
+
+`lib/cem_acpt/image_builder.rb:112-114`:
+
+```ruby
+def image_name_from_image_family(image_family)
+  "#{image_family}-v#{@start_time.to_i}"[0..64]
+end
+```
+
+`String#[0..64]` is **inclusive** on both ends — it returns up to 65
+characters. [`docs/ARCHITECTURE.md` §12 / §19 (item 11)](../ARCHITECTURE.md#19-open-questions--observed-dead-code)
+note the off-by-one.
+
+GCE rules (per [GCP docs][1]): image name must match
+`[a-z]([-a-z0-9]*[a-z0-9])?`, length 1-63.
+
+[1]: https://cloud.google.com/compute/docs/reference/rest/v1/images
+
+## Problem
+
+- An `image_family` of length ≥ 51 plus `-v` (2 chars) plus a 10-digit
+  unix timestamp (12 chars total) produces a name of 63+ chars,
+  which the current slice may or may not truncate to a value GCE
+  accepts.
+- Even when GCE accepts the name, the truncation can land on the `-v`
+  separator or mid-timestamp, producing a value that collides with
+  another build in the same family.
+
+## Proposal
+
+Use an exclusive cap and align with GCE's documented 63-char limit:
+
+```ruby
+GCE_IMAGE_NAME_MAX = 63
+
+def image_name_from_image_family(image_family)
+  full = "#{image_family}-v#{@start_time.to_i}"
+  return full if full.length <= GCE_IMAGE_NAME_MAX
+
+  # Preserve the timestamp suffix; truncate the family.
+  suffix = "-v#{@start_time.to_i}"
+  prefix = image_family[0, GCE_IMAGE_NAME_MAX - suffix.length]
+  prefix.sub(/-+\z/, '') + suffix
+end
+```
+
+This guarantees:
+
+- Length ≤ 63.
+- The timestamp suffix is intact, so two consecutive builds in the
+  same family never collide.
+- Trailing dashes from a clipped prefix are removed (GCE rejects names
+  ending in `-`).
+
+Add a unit test covering: short name unchanged, exact 63-char name
+unchanged, 64-char overflow truncated cleanly, prefix-ending-in-dash
+case.
+
+## Alternatives Considered
+
+- **Refuse to build if `image_family` itself is over the limit.**
+  Catches user error but doesn't help when timestamps push a
+  borderline name over.
+- **Hash the family into a fixed prefix.** Stable but loses
+  human-readability of image names.
+
+## Risks & Migration
+
+- User-visible change: image names that previously wrapped to 65
+  chars (and silently failed at GCE) will now succeed.
+- No config schema change.
+
+## Acceptance Criteria
+
+- [x] `image_name_from_image_family` enforces a 63-char cap.
+- [x] Generated names never end in `-`.
+- [x] RSpec coverage for the four cases above.
+- [x] [`docs/ARCHITECTURE.md` §12](../ARCHITECTURE.md#12-cem_acpt_image-image-builder-lifecycle)
+      updated to reflect the corrected behavior.
+
+## Implementation
+
+Implemented in CEM-6713. `GCE_IMAGE_NAME_MAX = 63` is defined on
+`TerraformBuilder`; `image_name_from_image_family` clips the family
+portion when needed and preserves the `-v<unix_ts>` suffix verbatim.
+RSpec coverage lives in
+[`spec/cem_acpt/image_builder_spec.rb`](../../spec/cem_acpt/image_builder_spec.rb)
+under `#image_name_from_image_family`.

data/docs/rfcs/0005-os-dispatch-replace-windows-heuristic.md

@@ -0,0 +1,117 @@
+# RFC 0005: Replace `tests.first.include?('windows')` with explicit OS dispatch
+
+- **Status:** Implemented
+- **Author:** TBD
+- **Created:** 2026-04-30
+- **Implemented:** 2026-05-05 (CEM-6714)
+- **Priority:** High
+- **Category:** Refactor
+- **Affected components:** `lib/cem_acpt/test_runner.rb`, `lib/cem_acpt/provision/terraform/`, `lib/cem_acpt/test_data.rb`
+
+## Summary
+
+The test runner decides whether to enter the Windows code path with
+`config.get('tests').first.include?('windows')`. This is a fragile
+substring match against an arbitrary test name and breaks down the
+moment a single run mixes OS targets or a test name happens to contain
+the substring. Replace it with an OS classification derived from the
+already-existing `Provision::OsData` machinery.
+
+## Background
+
+`lib/cem_acpt/test_runner.rb:65`:
+
+```ruby
+if config.get('tests').first.include? 'windows'
+  upload_module_to_bucket
+  @instance_names_ips.each { |k, v| ... WinRMRunner ... }
+end
+```
+
+`Provision::Terraform` already classifies the run by inspecting
+`@provision_data[:test_data].first[:test_name]` against
+`Linux.valid_names` and `Windows.valid_names` to pick a backend
+(see [`docs/ARCHITECTURE.md` §7](../ARCHITECTURE.md#7-provisioner-terraform)).
+That logic is the source of truth for "which OS family does this run
+target"; the runner is reinventing — and weakening — it.
+
+## Problem
+
+1. **Fragile match.** `tests.first.include?('windows')` is a
+   substring check. A test named `cis_rhel-8_firewalld_windowserver_2`
+   would falsely route to the Windows path.
+2. **Only inspects the first test.** A run with a mix of
+   `windows-2022_…` and `rhel-8_…` test names silently mishandles all
+   tests after the first.
+3. **Couples the runner to test-name spelling.** Renaming the
+   convention (`win` vs `windows`) breaks the heuristic.
+4. **Duplicates logic.** `Provision::OsData.use_for?` already answers
+   "is this a Windows test name?" correctly.
+
+## Proposal
+
+Introduce a single helper in `Provision::OsData` (or surface the one
+that exists) and consume it from the runner:
+
+```ruby
+# lib/cem_acpt/provision/terraform/os_data.rb
+def self.os_family_for(test_name)
+  return :windows if Windows.use_for?(test_name)
+  return :linux   if Linux.use_for?(test_name)
+  raise Error, "Cannot determine OS family for test name: #{test_name}"
+end
+```
+
+Then in the runner:
+
+```ruby
+windows_tests, linux_tests = config.get('tests').partition do |t|
+  CemAcpt::Provision::OsData.os_family_for(t) == :windows
+end
+
+unless windows_tests.empty?
+  raise 'Mixed Windows and Linux runs are not supported' unless linux_tests.empty?
+  upload_module_to_bucket
+  @instance_names_ips.each do |name, info|
+    win_node = ...
+    win_node.run
+  end
+end
+```
+
+This:
+
+- moves the OS decision to the place that already owns it,
+- explicitly surfaces the "mixed run" case rather than silently
+  doing the wrong thing,
+- removes the substring-match foot-gun.
+
+A follow-up could lift this further: per-test OS dispatch (so a single
+`cem_acpt` invocation can mix Linux and Windows tests). That is
+larger; this RFC is just about closing the obvious correctness gap.
+
+## Alternatives Considered
+
+- **Add an explicit `os: windows` config knob.** Possible, but the
+  test names already encode the OS and the provisioner already
+  parses them.
+- **Tag tests with metadata at discovery time.** Cleaner long term;
+  out of scope for this RFC.
+
+## Risks & Migration
+
+- Behavior change for the (unsupported) mixed-OS case: it now raises
+  rather than silently mis-routing. This is the desired change.
+- A test directory whose name does not match either `Linux.valid_names`
+  or `Windows.valid_names` would now fail-fast at preflight rather than
+  later in provisioning. This too is desired.
+
+## Acceptance Criteria
+
+- [ ] `Provision::OsData.os_family_for` (or equivalent) added with
+      RSpec coverage.
+- [ ] `test_runner.rb` no longer references `tests.first.include?`.
+- [ ] RSpec test demonstrates a mixed-OS config produces a clear
+      error.
+- [ ] [`docs/ARCHITECTURE.md` §4 / §13](../ARCHITECTURE.md#4-cem_acpt-test-runner-lifecycle)
+      updated.