mando-cli v3

Third iteration of the mando-cli tooling. Builds on the Page UI framework and adds developer-facing release automation as the first command implemented in v3.

Implemented Commands

mando release (dev-only)

Automated release workflow: bumps semver, generates changelog, commits, and tags.

Debug-Only

This command is gated behind #[cfg(debug_assertions)] — it compiles only in debug builds. The clap variant is named _Release (prefixed underscore) and mapped to the subcommand name release.

Usage:

mando release patch -c "Fix: queue timeout" -c "Feature: retry logic"
mando release minor -c "Feature: new API endpoint"
mando release major -c "Breaking: removed v1 compat"

Arguments:

Arg	Type	Required	Description
bump	positional, BumpLevel enum	yes	major, minor, or patch (clap ValueEnum)
-c	repeatable string	yes (at least 1)	Changelog entries, passed multiple times

What it does (in order):

1. Finds the nearest Cargo.toml by walking up from cwd
2. Reads current version via toml_edit::DocumentMut
3. Bumps semver according to BumpLevel (resets lower components)
4. Sorts changelog entries alphabetically (case-insensitive, sort_unstable_by)
5. Renders a date-stamped changelog section (## vX.Y.Z — YYYY-MM-DD)
6. Prepends the section to CHANGELOG.md (creates if missing)
7. Updates Cargo.toml version using toml_edit (preserves formatting/comments)
8. Stages Cargo.toml + CHANGELOG.md, commits release X.Y.Z, creates annotated tag vX.Y.Z
9. Renders a summary via the Page UI system showing version transition, tag, and step results

For Agents

The release command is dispatched from main.rs via Commands::_Release { bump, changes }. The implementation lives entirely in src/commands/dev_release.rs. The BumpLevel enum is defined in src/cli.rs. The module is conditionally compiled: #[cfg(debug_assertions)] pub mod dev_release in src/commands/mod.rs.

Files Changed

File	Change
src/cli.rs	Added BumpLevel enum (ValueEnum), added _Release variant with #[cfg(debug_assertions)]
src/commands/dev_release.rs	Full implementation (~160 lines): version read/bump, changelog render, toml update, git ops, Page output
src/commands/mod.rs	Added #[cfg(debug_assertions)] pub mod dev_release
src/main.rs	Wired Commands::_Release dispatch to dev_release::run()
Cargo.toml	Added toml_edit = "0.22" dependency

Key Implementation Details

Semver Bumping

match bump {
    BumpLevel::Major => { major += 1; minor = 0; patch = 0; }
    BumpLevel::Minor => { minor += 1; patch = 0; }
    BumpLevel::Patch => { patch += 1; }
}

Validates strict 3-component semver (MAJOR.MINOR.PATCH). Rejects pre-release and build metadata with a clear error message.

Cargo.toml Editing

Uses toml_edit (not toml or regex) to preserve formatting, comments, and key ordering when updating [package].version.

Git Operations

Runs git add, git commit -m "release {version}", and git tag -a vX.Y.Z -m "release {version}" via std::process::Command with OsStr args for path safety. Failures surface the git stderr message via anyhow::bail!.

Dependencies Added

Crate	Version	Purpose
toml_edit	0.22	Lossless TOML parsing and editing
chrono	(existing)	Date formatting for changelog headers

Related

• mando-cli — v1 YAML recipe runner
• mando-cli-v2 — v2 IoC framework and Page UI system
• Mando — the workspace being managed
• Alpiq BESS — project overview