preview_executor 0.1.0

Execute an ordered list of steps, each of which states what it would do before anything runs — and is held to it. Transport-neutral engine behind CLI plan/apply and HTTP dry-run.

Changelog

All notable changes to this project will be documented in this file.

The format loosely follows Keep a Changelog and the project adheres to Semantic Versioning.

0.1.0

First release. The engine and nothing else.

Added

• Step — one unit of work, with preview() and perform(context) as two separate methods. Not one method with a dry-run flag: a flag threaded through the work leaves nothing holding the switched-off pass and the real one to the same behaviour, which is how a preview drifts from what it describes without anybody finding out
• PreviewExecutor — preview(steps) collects what the steps say they would do and touches nothing; perform(steps) runs them in order and checks each report against the claim the step made immediately before
• Preview / Outcome — the claim and the report, shaped alike so they can be compared. verb and target are the claim and are checked; detail is prose for a reader and is not
• Preview.pending — the names of values a step cannot know until it has run. A preview that stayed silent about them would read as complete when it was not; declaring them lets a host render known once this runs, and holds the step to producing every one
• StepContext — what a step can see of the steps before it, looked up by the step object rather than by name or index. Only backwards, which is what makes an ordered list sufficient and a dependency graph unnecessary
• Execution — answers isComplete (did every step run) and isFaithful (did every step that ran keep its word) apart, because they fail for different reasons and deserve different responses
• Discrepancy — a step that acted differently from its own preview, or named a pending value and came back without it
• StepFailure — a step that threw. Reported rather than rethrown: a list that stops halfway has left a state somebody has to understand, and an exception carrying only its own message takes the record of that state with it

Notes

• No approval, no rendering, no I/O. The decision between previewing and performing belongs to the host, and so does turning either into text. That is what lets the same engine sit behind a CLI's --plan / --apply and an HTTP endpoint's dry-run