> envman status
Using profile development
app: `web_app` out-of-date
server: not exists
upload: `web_app` not uploaded

> envman diff
app: `web_app` will be compiled
server: will be launched
upload: `web_app` will be uploaded

Automation is not just about performant execution, but understanding the state of things, and what automation would alter.

Understanding is not "how much information can be output", but "how information is best presented".

Peace presents the highest value information at a glance, with easy options to go deeper.

> envman ensure  # interactive
✅ app    ▰▰▰▰▰▰▰▰▰▰▰▰▰ built in 4s
🔨 server ▰▰▰▰▱▱▱▱▱▱▱▱▱ el: 7s, eta: 9s
⏳ upload ▱▱▱▱▱▱▱▱▱▱▱▱▱ deps: [server]

* To stop, press Ctrl + C
* For detail, in another terminal run:
  envman progress --detail

# ci
server | 1/5 |  0s | vm requested
app    | 1/1 |  4s | built
server | 2/5 |  7s | os booted
server | 3/5 | 10s | pkgs installed

Peace presents information and actions adaptively:

• Progress presented as bars when used interactively, and single line logs in CI.
• JSON when returned as a web response.
• HTML elements when rendered in a browser -- WASM / web application.

> envman ensure
✅ app    ▰▰▰▰▰▰▰▰▰▰▰▰▰ built in 4s
⚠️ server ▰▰▰▰▰▰▰▱▱▱▱▱▱ el: 33s, eta: 7s
⏳ upload ▱▱▱▱▱▱▱▱▱▱▱▱▱ deps: [server]

* To stop, press Ctrl + C
* For detail, in another terminal run:
  envman progress --detail

⚠️ warn: server may have stalled.
  Last message:  (9s ago)
  Running `sudo apt install -y sysstate` 

Peace automatically tracks execution metrics. This enables:

• Proactive Outlier Detection: Prompts based on outliers to historical averages.
• Highest Impact Optimization: Targeting efficiency improvements at the most frequent operations, or the slowest processes.

> envman ensure
✅ app    ▰▰▰▰▰▰▰▰▰▰▰▰▰ built in 4s
❌ server ▰▰▰▰▰▰▰▱▱▱▱▱▱ el: 33s, eta: 7s
🚫 upload ▱▱▱▱▱▱▱▱▱▱▱▱▱ deps: [server]

Error: server_package_install

  × Server packages failed to install.
  ╰─▶ Unable to locate package sysstate
   ╭─[server/config.yaml:1:1]
 1 │ packages:
 2 │ - sysstate
   ·   ───┬────
   ·      ╰── defined here
   ╰────
   Help: Ensure spellings are correct

Peace presents errors in the much loved Rust compiler error format, through compatibility with miette by design.

• The source parameter(s) that cause the error are presented to the user, reducing work to find it.
• Suggestions on how to recover help the user move forward.

People don't feel lost when what they do doesn't work; they feel lost when they don't have a way to move forward.

> envman log
profile: development
2023-01-25+1300 (2 days ago)
* ✅ 8 15:28:20 envman clean
* ✅ 7 14:56:32 envman ensure
* ✅ 6 14:48:22 envman ensure
* ❌ 5 14:47:19 envman ensure
* ✅ 4 14:31:48 envman ensure
2023-01-24+1300 (3 days ago)
* ✅ 3 17:05:17 envman clean
* ✅ 2 16:32:08 envman ensure
* ✅ 1 16:29:59 envman ensure

> envman show
last execution: 8
command: envman clean
2023-01-25T15:28:20+1300 (2 days ago)

app:    up-to-date    to not-exists
server: `abc-103abfe` to None
upload: n/a

Peace stores execution summaries in its structured form, making it easy to review what was done, or analyzed with a different presentation.

trait ItemSpec {
    type State:  /* .. */;
    type StateDiff:  /* .. */;
    async fn state_current(&self, ..) -> _;
    async fn apply_exec(&self, ..) -> _;
    /* .. */
}

impl Presentable for ServerState {
    fn present(&self, presenter: &Presenter) {
        presenter
            .name(self.server_name)
            .desc(self.server_status)
    }
}

Compile time constraints (with all features) means correctness, safety, and ease-of-use by design:

• For every item creation, there is a clean up.
• Every command has a target state, so multiple executions is not dangerous.
• Item states must be:
  • Fetchable: For idempotence, this allows automation to skip to where it stopped.
  • Presentable: In short for comprehension, in detail for informed decisions.
• Constraints enable Peace to provide common flows, and adapt information for each target.

⛓️ It is these constraints that give us freedom

[dependencies.peace]
version = "0.0.?"
features = [
    "error_reporting",
    "output_colorized",
    "output_json",
    "output_progress",
    "state_current",  # 🚧
    "state_goal",     # 🚧
    "state_diff",     # 🚧
    # ..
]

🐚 Instead of writing shell scripts, then transitioning to larger tools as complexity grows, existing logic is extended by enabling features in the Peace crate.

 async fn apply_exec(
     state_current: Self::State,
     state_goal: Self::State,
+    state_diff: Self::StateDiff,
 ) -> Result<(), E>

🦀 Compilation errors show the code that needs updating, you don't have to work to find out.

A collection of functions to manage an item, e.g. application compilation, file upload, server existence.

Base functions:

• Current: Retrieve the current state.
• Goal: Retrieve the goal state.
• Diff: Diff the current and goal states.
• Ensure: Change the state from current to goal.
• Clean: Clean up the item.
• more to come

A directed graph of Item Specs. Edges indicate forward execution order.

Functions can be executed in parallel when their predecessors' executions are complete.

A flow is a process that fulfills a business question or intent. Within a flow, the appropriate Item Specification function(s) are invoked for each item.

Examples:

• Discover and show the state of all items.
• Show what would change.
• Execute the automation.

Advanced flows may invert execution direction:

• clean cleans up items in reverse order.
• ensure on a subset of items may forward alter some items, and clean others.