Terminal UI & Prompts

Relevant source files

The following files were used as context for generating this wiki page:

• src/ui.rs
• src/init.rs
• src/executor.rs
• src/config.rs
• src/main.rs
• README.md

The Terminal UI and Prompting system in cargo-cooldown provides interactive feedback and configuration utilities for users. It encompasses progress indicators during the dependency cooling process, status reporting for lockfile mutations, and an interactive setup wizard for initializing project configurations. The system is designed to respect terminal capabilities, disabling animations and colors when output is piped or explicitly configured to be plain text.

Sources: src/ui.rs:1-5, src/init.rs:31-38, src/executor.rs:105-110

Progress Management

The UI system utilizes the indicatif library to manage terminal progress during the resolver's execution passes. It distinguishes between transient "phases" and numeric progress based on the number of fresh crates remaining to be cooled.

Phase and Progress Indicators

The system uses two primary handles for terminal feedback:

• PhaseStatus: A short-lived spinner used for pre-scan activities like capturing baselines or running cargo update. It clears itself upon completion or error to prevent terminal clutter.
• UserOutput: A long-lived handle that manages the main resolver progress bar. It tracks the maximum number of fresh crates seen to ensure the progress bar moves monotonically even if the dependency graph changes during passes.

Sources: src/ui.rs:59-65, src/ui.rs:113-118, src/ui.rs:154-159

Terminal Capability Detection

Interactive elements and styles are adjusted based on the environment:

• Colors: Enabled if the output is a TTY and the NO_COLOR environment variable is absent. It also respects the CARGO_TERM_COLOR setting.
• Progress Animation: Enabled only if the terminal is a TTY and verbose mode is disabled. It is also suppressed if CARGO_TERM_PROGRESS_WHEN is set to never.

Sources: src/ui.rs:194-205, src/ui.rs:207-217

The diagram shows the logic used to determine terminal capabilities for colors and animations. Sources: src/ui.rs:72-85, src/ui.rs:194-217

Interactive Setup Wizard

The init module provides a prompting system for creating cooldown.toml files. It performs project discovery and asks the user a series of configuration questions.

Prompt Types

The wizard implements several specialized prompt types to gather structured data:

• Confirm: A Yes/No prompt (e.g., "Write these files?").
• Input: Standard text input with optional default values.
• Select/Multi-Select: Used for choosing enforcement modes or selecting specific workspace members for configuration overrides.
• Integer (u64): Specifically for setting cooldown minute durations.

Sources: src/init.rs:200-260, src/init.rs:288-315

Workspace Configuration Flow

When running in a workspace, the UI directs a multi-step selection process:

1. Scope Selection: Asks if the configuration is workspace-wide or includes per-member overrides.
2. Member Selection: If overrides are chosen, provides a numbered list of workspace members for the user to select.
3. Template Generation: Renders a preview of the .toml contents to the terminal before requesting final write confirmation.

Sources: src/init.rs:82-114, src/init.rs:317-340

Sequence of interactions during the cargo cooldown init command. Sources: src/init.rs:39-71, src/init.rs:186-198

Status Reporting

Status lines are formatted to match standard Cargo output, providing a consistent aesthetic for lockfile mutations and resolver summaries.

Status Categories

Mutations to the dependency graph are categorized using StatusKind:

Status Kind	Label	Color	Description
Adding	Adding	Cyan	A new crate version is being introduced.
Updating	Updating	Green	A crate is being moved to a newer (but still cool) version.
Downgrading	Downgrading	Green	A crate is being moved to an older version to satisfy cooldown.
Removing	Removing	Red	A crate version is being removed from the graph.
Keeping	Keeping	Yellow	A version is being held at its current state despite newer available versions.
Warning	Warning	Yellow	A fresh version remains that could not be cooled.
Finished	Finished	Green	Cooldown process completed successfully.

Sources: src/ui.rs:19-53, src/executor.rs:240-265, src/executor.rs:480-495

Summary Formatting

At the end of a run, the system emits a summary. If enforcement = "cargo_compatible" is set and fresh versions remain, the UI presents an interactive prompt to the user to accept these versions.

Sources: src/executor.rs:360-385, src/executor.rs:428-442

// src/ui.rs:186-192
pub fn format_status_line(kind: StatusKind, message: &str, use_color: bool) -> String {
    let label = format!("{:>width$}", kind.label(), width = STATUS_WIDTH);
    if !use_color {
        return format!("{label} {message}");
    }

    format!("{}{}{} {}", kind.color_code(), label, ANSI_RESET, message)
}

Sources: src/ui.rs:186-192

Error and Warning Presentation

The UI system handles critical user interventions, particularly when enforcement policies are violated.

• Strict Enforcement Failure: If enforcement = "strict" is active and fresh versions cannot be cooled, the UI returns a detailed error message listing all offending crates and their publish dates.
• Confirmation Requests: Under cargo_compatible enforcement with cargo_compatible_accept = "prompt", the system will stall and wait for a y/N response if a fresh version is required by Cargo. If the terminal is non-interactive in this state, the process fails with an error message instructing the user to use auto accept.

Sources: src/executor.rs:365-385, src/executor.rs:397-420, src/config.rs:45-60

Summary

The Terminal UI & Prompts system is responsible for ensuring the user is informed of the cooling process and the resulting state of the Cargo.lock file. By mirroring Cargo's status formatting and providing structured interactive wizards, it maintains a familiar experience for Rust developers while enforcing the supply-chain security goals of the project.