Write the --simulate change set as JSON (--simulate-json)

[djbclark]

The change set a --simulate run computes can currently only come out as prose — the manifest/diff printers are written for a human to read, and the internal record files aren't a stable format anyone else is meant to parse. So if you wanted a program (not a person) to know what CFEngine would do, it had nothing reliable to read. This adds a --simulate-json=FILE flag that writes the same information out as a single structured JSON document instead.

Why that's interesting: once the predicted change set is real, versioned data instead of text for humans, it stops being a report and starts being an API:

• Build a CI gate that fails the pipeline if a policy change would touch files it shouldn't — no text-scraping required.
• Feed it into a diffing/visualization tool to show "here's exactly what this run will do" in a UI, not a wall of text.
• Compare the JSON from two runs programmatically to catch policy drift or unintended side effects over time.
• Let other tooling in the ecosystem (dashboards, audit systems, other CFEngine wrappers) consume CFEngine's intentions without depending on prose that can be reworded at any time.

---

The changes computed by a --simulate run can only be rendered as prose meant for human eyes: the manifest and diff renderers print free-form text, and the record files in the changes chroot are an internal, unstable format. Any program consuming the simulated change set has to parse text that can be reworded at any time.

Proposal: a new --simulate-json=FILE option. cf-agent also writes the change set to FILE as a single JSON document: which files would be created, modified or deleted (with type, permissions, ownership, size and SHA-256 content digest they would have after the run), which files would be renamed, and which packages would be installed or removed. The document carries a format_version field so consumers can detect future structure changes. Requires --simulate and an absolute path. The prose renderers are unchanged and remain the default; without the option, nothing changes.

PR: #6294

[djbclark]

Now tracked in Jira as CFE-4716.

As with #6295, this discussion existed because we couldn't reach the CFE tracker; that's now sorted (thanks to @nickanderson for the project permission).

One correction to the proposal above: it says "the prose renderers are unchanged and remain the default; without the option, nothing changes." The second half is right and was verified by measurement — file-level --simulate=manifest and --simulate=diff output is byte-identical with the option absent. The first half is not accurate as written, because DiffPkgOperations() was rewritten to share a reduction step with the JSON path. That rewrite also carried forward a pre-existing bug where a remove-then-install sequence is reported as both operations rather than cancelling. CFE-4716 has the full list.

Future feature proposals from us will go to Jira rather than new discussions.

[larsewi]

Closing in favor of ticket CFE-4716