cem_acpt 0.11.0 → 0.11.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1e3e1c15beb777d80ea6a65241d1433901f6d627eabd4f11be9547f79e941c03
-  data.tar.gz: bef63cc44f4e536da21599b01d00dc51524f60240e42ad22f23df6e5fadb36b7
+  metadata.gz: df61aa1c290a076e460b4c790babb19d0e0729e7d543feb96a9fb40e1589e50a
+  data.tar.gz: 800a652e59491e42f0e3fdd43db93e397956309e2b575d33e0f2c1497ebd8311
 SHA512:
-  metadata.gz: 28f8b379445b92a4ff5e7df0fcd1a2f7385d7a6ee86c47bfdd825be23beb79c60752580e8c62c29f39d5fa5c3f623cc4834c4237679f74b19b847448ed16518f
-  data.tar.gz: 681f5f556c8ddcdc523db369c207e19c96e7378a82299862d10002fa9cc2d02ea8e6a3a416d84fd68594d194218e415f1a137b511bd0786386e0330a714518c5
+  metadata.gz: a4a93419e474a066291ead08cbb28222f635f218b3df394b92f8c23d2fc1d63d55b9c5e240229c86db22a7b98e0e8673a5f13c7d02bd0d3633976942cc22be08
+  data.tar.gz: 614ecdad289b17a01ffcaea724aa928372cf578a4270f641e592549a6f2d017235646fe5ab8b3274e23801755935b6d7e17cdd39072aee28cbc7692b86e5b663

data/.gitignore

@@ -16,3 +16,11 @@ profile.txt
 
 # local dev
 run_script.rb
+
+# Ignore .env files which may contain sensitive information
+.env
+.env.*.local
+
+# Local Claude configuration
+.claude/settings.local.json
+.claude/worktrees/

data/.worktreeinclude

@@ -0,0 +1 @@
+.env

data/CLAUDE.md

@@ -2,75 +2,113 @@
 
 ## What This Project Is
 
-`cem_acpt` is a Ruby gem providing an acceptance testing CLI for Puppet SCE (Security Compliance Enforcement), formerly known as Puppet CEM (Compliance Enforcement Modules). It provisions cloud nodes via Terraform, applies a Puppet manifest to the node, runs infrastructure tests via Goss, and tears everything down. It is also capable of running Puppet Bolt tests, which validate Bolt tasks and plans. A second binary, `cem_acpt_image`, builds the base VM images used by the test runner.
+`cem_acpt` is a Ruby gem providing an acceptance testing CLI for Puppet SCE (Security Compliance Enforcement, formerly Puppet CEM / Compliance Enforcement Modules). It provisions cloud nodes via Terraform, applies a Puppet manifest, runs infrastructure tests via Goss (and optionally Bolt task/plan tests), then tears everything down. Both Linux nodes (over SSH) and Windows nodes (over WinRM) are supported.
+
+A second binary, `cem_acpt_image`, builds the base VM images used by the test runner.
+
+The gem name is intentionally unchanged after the CEM → SCE rename. The consuming Puppet modules were renamed to `sce_linux` / `sce_windows`, but this gem stays `cem_acpt`.
+
+## Where to Read More
+
+Before diving into the summary below, skim:
+- `docs/ARCHITECTURE.md` — fuller architecture writeup
+- `docs/rfcs/` — design decisions (Windows image builder, OS dispatch, platform namespacing, logging behavior, etc.). Check here before proposing structural changes.
 
 ## Commands
 
 ```bash
 bundle install          # Install dependencies
 
-bundle exec rake spec                                  # Run all the spec tests
+bundle exec rake spec                                  # Run all spec tests
 bundle exec rake spec SPEC=spec/path/to/file_spec.rb   # Run a single spec file
 
 rubocop                 # Lint
 rubocop -a              # Auto-fix lint issues
 
 bundle exec rake build                           # Build the gem (saves to pkg/cem_acpt-<semver>.gem)
-bundle exec gem install pkg/cem_acpt-X.X.X.gem   # Install the gem with the given semver (X.X.X should be replaced with a version)
+bundle exec gem install pkg/cem_acpt-X.X.X.gem   # Install built gem
 
 bundle exec exe/cem_acpt -h       # CLI help
-bundle exec exe/cem_acpt -Y       # Print merged config (useful for debugging)
+bundle exec exe/cem_acpt -Y       # Print merged config as YAML
 bundle exec exe/cem_acpt -X       # Explain config merge sources
 ```
 
-RuboCop target is Ruby 3.2. Line length limit is 200. Many complexity metrics (AbcSize, MethodLength, ClassLength) are disabled.
+CI runs `bundle exec rake spec` on PRs against `main` (see `.github/workflows/spec.yml`). Lint is not currently gated in CI, but RuboCop should be clean before merging.
+
+RuboCop targets Ruby 3.2 with a 200-char line limit. The config in `.rubocop.yml` is intentionally permissive — many cops (complexity, layout, style) are disabled. Check `.rubocop.yml` before assuming a rule is enforced.
 
 ## Architecture
 
 ### Entry Points
 
-- `exe/cem_acpt` → `lib/cem_acpt.rb` → dispatches to `TestRunner::Runner`
-- `exe/cem_acpt_image` → `lib/cem_acpt.rb` → dispatches to `ImageBuilder::TerraformBuilder`
-- CLI parsing lives in `lib/cem_acpt/cli.rb` (Ruby `OptionParser`)
+- `exe/cem_acpt` and `exe/cem_acpt_image` both call into `CemAcpt.run` in `lib/cem_acpt.rb`, which dispatches on the command:
+  - `:cem_acpt` → `TestRunner::Runner`
+  - `:cem_acpt_image` → `ImageBuilder::TerraformBuilder`
+  - `:print_yaml_config` / `:print_explain_config` → handle the `-Y` / `-X` debugging flags
+  - `:version` → prints gem version
+- CLI parsing lives in `lib/cem_acpt/cli.rb` (Ruby `OptionParser`).
 
 ### Configuration System (`lib/cem_acpt/config/`)
 
-Config is merged from four sources, lowest to highest priority:
+Config is built by merging four sources, with each later source overriding earlier ones:
+
 1. Environment variables (`CEM_ACPT_` prefix; nested keys use `__`)
 2. User config at `~/.cem_acpt/config.yaml`
 3. `--config FILE` option
 4. Other CLI flags
 
-`Config::Base` handles the merge logic via `deep_merge`. Subclasses `Config::CemAcpt` and `Config::CemAcptImage` define the schema for each command.
+`Config::Base` handles the merge via `deep_merge`. `Config::CemAcpt` and `Config::CemAcptImage` define the schema for each command. Use `-Y` to print the merged result and `-X` to see which source contributed each value.
 
 ### Test Runner Lifecycle (`lib/cem_acpt/test_runner.rb`)
 
-1. **Pre-provision** – Build the Puppet module tarball (`Utils::Puppet`)
-2. **Provision** – Spin up GCP nodes via Terraform (`Provision::Terraform`), generate ephemeral SSH keys, install the module
-3. **Execute** – Run action groups: `:goss` (async, HTTP) and `:bolt` (sync, Puppet tasks)
-4. **Cleanup** – `terraform destroy` unless `--no-destroy-nodes`
+1. **Pre-provision** — Build the Puppet module tarball (`Utils::Puppet`).
+2. **Provision** — Spin up nodes via the configured platform (currently only GCP) using Terraform (`Provision::Terraform`), generate ephemeral SSH keys (or set up WinRM for Windows), and install the module.
+3. **Execute** — Run action groups: `:goss` (async, HTTP) and `:bolt` (sync, Puppet tasks). Filter with `--only-actions` / `--except-actions`.
+4. **Cleanup** — `terraform destroy` unless `--no-destroy-nodes`.
 
 ### Platform Abstraction (`lib/cem_acpt/platform/`)
 
-`Platform::Base` defines the interface; `Platform::Gcp` implements GCP-specific behaviour. Platforms are loaded dynamically by name from the config.
+`Platform::Base` defines the interface; `Platform::TestBase` extends it for test-node platforms. `Platform::Gcp` is the only concrete implementation today, but platforms are loaded dynamically by name from config — so adding e.g. AWS means a new file here plus a Terraform tree under `lib/terraform/`.
 
 ### Actions (`lib/cem_acpt/actions.rb`)
 
-The `Actions` class orchestrates test execution. Action groups can be filtered with `--only-actions` / `--except-actions`. Goss actions run async via `async-http`; Bolt actions run synchronously.
+The `Actions` class orchestrates test execution. Actions register themselves via `register_action`/`register_group` and run in `order` order. Goss actions run asynchronously via `async-http`; Bolt actions run synchronously.
+
+### Transports
+
+- **SSH** (`lib/cem_acpt/utils/ssh.rb`) — Linux nodes
+- **WinRM** (`lib/cem_acpt/utils/winrm_runner.rb`) — Windows nodes
+- **Goss HTTP API** (`lib/cem_acpt/goss/api.rb`) — assertions, on a port exposed by the provisioned node
 
 ### Terraform Templates (`lib/terraform/`)
 
-Terraform HCL lives inside the gem under `lib/terraform/`. Paths:
-- `lib/terraform/gcp/linux/` and `lib/terraform/gcp/windows/` – test node provisioning
-- `lib/terraform/image/gcp/linux/` – image-building node provisioning
+Terraform HCL ships inside the gem:
+- `lib/terraform/gcp/linux/` and `lib/terraform/gcp/windows/` — test-node provisioning
+- `lib/terraform/image/gcp/linux/` and `lib/terraform/image/gcp/windows/` — image-building provisioning
 
 ### Logging (`lib/cem_acpt/logging/`)
 
-Supports simultaneous STDOUT + file logging. Pass `-I` / `--CI` for GitHub Actions–formatted output. Pass `--trace` to enable Ruby `TracePoint` debugging.
+Supports simultaneous STDOUT + file logging. `-I` / `--CI` enables GitHub Actions–formatted output. `--trace` enables Ruby `TracePoint` debugging. Most subsystems include `CemAcpt::Logging` to get a `logger` method.
+
+## Where to Add Things
+
+| Adding…                       | Touch                                                                                          |
+| ----------------------------- | ---------------------------------------------------------------------------------------------- |
+| A new platform (e.g. AWS)     | `lib/cem_acpt/platform/<name>.rb` (subclass `Platform::TestBase`) + `lib/terraform/<name>/...` |
+| A new action group            | Register in `lib/cem_acpt/actions.rb`; add a subdir under `lib/cem_acpt/<group>/`              |
+| A new config option           | Add to `lib/cem_acpt/config/cem_acpt.rb` (or `cem_acpt_image.rb`) and wire into `cli.rb`       |
+| A new Bolt helper             | `lib/cem_acpt/bolt/` — see `inventory.rb`, `tasks.rb`, `tests.rb` for the existing pattern     |
+| A new utility (SSH/WinRM/etc) | `lib/cem_acpt/utils/`                                                                          |
 
 ## Test Structure
 
-Acceptance test cases live under `spec/acceptance/` (in the consuming module, not this gem):
+### Unit tests (this repo)
+
+Specs live under `spec/`, mirroring the layout of `lib/`. Fixtures live in `spec/fixtures/`. Run with `bundle exec rake spec`.
+
+### Acceptance tests (consuming module)
+
+Acceptance test cases live in the **consuming module** (e.g. `sce_linux`, `sce_windows`), not in this gem. They follow this layout:
 
 ```
 spec/acceptance/<framework>_<os>-<version>_<firewall>_<profile>_<level>/
@@ -79,9 +117,10 @@ spec/acceptance/<framework>_<os>-<version>_<firewall>_<profile>_<level>/
   bolt.yaml     # (optional) Bolt task assertions
 ```
 
-Unit tests mirror `lib/` under `spec/`. Fixtures are in `spec/fixtures/`.
-
 ## Conventions
 
-- Document all Ruby code using Yard comments
-- All changes should have tests
+- Document Ruby code with YARD comments.
+- All changes should have tests.
+- Subsystem-specific error classes live alongside the subsystem (e.g. `lib/cem_acpt/bolt/errors.rb`); follow that pattern rather than reusing generic `StandardError`.
+- Use `CemAcpt::Utils::FinalizerQueue` for ordered cleanup of provisioned resources rather than ad-hoc `ensure` blocks.
+- Mix in `CemAcpt::Logging` to get a logger; don't instantiate one directly.

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    cem_acpt (0.11.0)
+    cem_acpt (0.11.1)
       async-http (>= 0.60, < 0.70)
       bcrypt_pbkdf (>= 1.0, < 2.0)
       deep_merge (>= 1.2, < 2.0)

data/README.md

@@ -16,7 +16,7 @@ gem install cem_acpt
 
 ### Quickstart
 
-Make sure Terraform and the gcloud CLI are installed and in your PATH. Instructions for installing Terraform can be found [here](https://learn.hashicorp.com/tutorials/terraform/install-cli) and instructions for installing the gcloud CLI can be found [here](https://cloud.google.com/sdk/docs/install).Then, navigate to the root of the `cem_linux` module and run the following command:
+Make sure Terraform and the gcloud CLI are installed and in your PATH. Instructions for installing Terraform can be found [here](https://learn.hashicorp.com/tutorials/terraform/install-cli) and instructions for installing the gcloud CLI can be found [here](https://cloud.google.com/sdk/docs/install).Then, navigate to the root of the `sce_linux` module and run the following command:
 
 ```bash
 cem_acpt --config ./cem_acpt_config.yaml
@@ -140,7 +140,7 @@ All Bolt tasks are ran with the `--format json` flag, which returns a JSON docum
 
 Example:
 
-In this example, we will go over how a Bolt task's output would be evaluated by a Bolt test hash. This example assumes one Bolt task named `cem_linux::audit_sssd_certmap` that takes no parameters was ran successfully against two nodes.
+In this example, we will go over how a Bolt task's output would be evaluated by a Bolt test hash. This example assumes one Bolt task named `sce_linux::audit_sssd_certmap` that takes no parameters was ran successfully against two nodes.
 
 Bolt task JSON output:
 
@@ -150,7 +150,7 @@ Bolt task JSON output:
     {
       "target":"35.212.146.14",
       "action":"task",
-      "object":"cem_linux::audit_sssd_certmap",
+      "object":"sce_linux::audit_sssd_certmap",
       "status":"success",
       "value":{
         "sssd_certmap_exists":false
@@ -159,7 +159,7 @@ Bolt task JSON output:
     {
       "target":"35.212.197.53",
       "action":"task",
-      "object":"cem_linux::audit_sssd_certmap",
+      "object":"sce_linux::audit_sssd_certmap",
       "status":"success",
       "value":{
         "sssd_certmap_exists":false
@@ -174,7 +174,7 @@ Bolt task JSON output:
 Bolt test hash in `bolt.yaml`:
 
 ```yaml
-'cem_linux::audit_sssd_certmap':
+'sce_linux::audit_sssd_certmap':
   status: 'success'
   value:
     match: 'false'
@@ -335,6 +335,19 @@ images:
 
 See [sample_config.yaml](sample_config.yaml) for a more complete example.
 
-### Testing with cem_windows
+### Testing with sce_windows
 
-While testing with cem_windows follows pretty much the same outline as cem_linux, there are a few extra step that we have to do when bootstrapping the generated node. Two of the most prominents steps are enabling long path and using NSSM to start the goss service. When we enable long path on Windows, it allows the command `puppet module install` to install dependencies correctly (specifically the dsc modules). As for [NSSM](https://nssm.cc/), stands for Non-sucking service manager, it is necessary for us to use this tool because without it, we will not be able to create services for Goss. Windows services cannot run from an executable but rather through a Windows service project that can be build with Visual Studio. NSSM allows us to bypass having to create Windows service project for Goss and create services directly from the Goss executable.
+While testing with sce_windows follows pretty much the same outline as sce_linux, there are a few extra step that we have to do when bootstrapping the generated node. Two of the most prominents steps are enabling long path and using NSSM to start the goss service. When we enable long path on Windows, it allows the command `puppet module install` to install dependencies correctly (specifically the dsc modules). As for [NSSM](https://nssm.cc/), stands for Non-sucking service manager, it is necessary for us to use this tool because without it, we will not be able to create services for Goss. Windows services cannot run from an executable but rather through a Windows service project that can be build with Visual Studio. NSSM allows us to bypass having to create Windows service project for Goss and create services directly from the Goss executable.
+
+#### Configuring the GCS bucket
+
+The Windows test path uploads the Puppet module tarball to a GCS bucket so the test instance can `gcloud storage cp` it back down. The bucket name is configurable via `platform.gcp.windows_bucket` (default: `win_cem_acpt`):
+
+```yaml
+platform:
+  name: gcp
+  gcp:
+    windows_bucket: my-org-cem-acpt
+```
+
+Alternatively, pass `--windows-bucket BUCKET` on the CLI or set `CEM_ACPT_PLATFORM__GCP__WINDOWS_BUCKET` in the environment. The bucket must exist and be writable by the account running `cem_acpt`; it must also be readable by the service account attached to the Windows test instance.