Initialization Wizard

Relevant source files

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

• src/init.rs
• tests/init.rs
• src/main.rs
• src/config.rs
• README.md
• tests/cli.rs

The Initialization Wizard is an interactive setup tool provided by the cargo cooldown init command. Its primary purpose is to guide users through the creation of cooldown.toml configuration files, which define how the project handles freshly published registry crates. It is designed to be run from the project root and can handle both standalone crates and complex Cargo workspaces with multiple members.

Sources: src/init.rs:1-6, src/main.rs:105-115, README.md:46-48

Overview and Logic Flow

The wizard performs project discovery to identify whether it is operating within a single crate or a workspace. It then gathers user input through a series of prompts to generate a configuration plan. Before writing any files to disk, the wizard verifies that it will not overwrite existing cooldown.toml files and requires explicit user confirmation.

The high-level execution flow is as follows:

1. Discovery: Identify the project root and type (Crate vs. Workspace).
2. Configuration Prompting: Collect base settings (minutes, enforcement, etc.).
3. Member Overrides: (Workspace only) Optionally configure specific workspace members.
4. Plan Preview: Show the generated TOML content and file paths.
5. Safety Check: Check for existing files to avoid accidental overwrites.
6. Execution: Write the files upon user confirmation.

Sources: src/init.rs:43-85, tests/init.rs:88-93

Initialization Process Flow

The following diagram illustrates the logical steps taken by the wizard during a setup session.

Core Components and Data Structures

The wizard relies on internal structures to model the configuration templates and the intended file writes.

ConfigTemplate

Represents the settings gathered from the user during the interactive session.

• cooldown_minutes: Integer representing the age requirement for releases.
• enforcement: Policy for handling fresh versions (strict, cargo_compatible, or off).
• lockfile_baseline: Determines if the initial Cargo.lock is a version floor (floor or ignore).
• skip_registries: A list of registry URLs or names to exclude from cooling.
• include_allow_examples: Boolean to determine if commented-out examples are added to the TOML.

Sources: src/init.rs:13-20, src/config.rs:17-48

InitPlan

A collection of InitFile objects that describe exactly what will be written to the filesystem.

• path: The destination PathBuf for the file.
• contents: The rendered TOML string.

Sources: src/init.rs:22-30

Interactive Prompts and Defaults

The wizard uses a series of specialized prompting functions to ensure valid data entry.

Prompt Type	Default Value	Description
Cooldown Minutes	1440	Time in minutes a crate must be "cooled" before acceptance.
Enforcement	cargo_compatible	Action taken when fresh versions remain.
Lockfile Baseline	floor	Whether to treat existing lockfile versions as the minimum floor.
Registries to Skip	(None)	Comma-separated list of registries to ignore.
Allow Examples	True	Whether to include boilerplate [[allow.package]] examples.

Sources: src/init.rs:141-157, README.md:65-71

Prompt Sequence Diagram

The interaction between the user and the wizard follows a specific sequence to build the configuration.

Workspace Support and Overrides

In a Cargo workspace, the wizard offers a choice between a workspace-wide default configuration or a combination of workspace defaults and per-member overrides.

1. Workspace Defaults: Created at the workspace root as cooldown.toml.
2. Member Overrides: Created inside specific member directories. These files contain a specific header indicating they override workspace defaults when that member is the unique target of a command.

The build_workspace_plan function manages the selection of members for overrides using prompt_multi_select.

Sources: src/init.rs:94-138, README.md:144-148

Safety and Conflict Resolution

The wizard implements a "fail-safe" approach to file management:

• Path Discovery: It uses project.workspace_config_path() to ensure files are placed correctly.
• Collision Detection: It checks every path in the InitPlan against the filesystem. If any file already exists, it prints the conflicting paths and bails with the message: refusing to overwrite existing cooldown.toml files.
• Confirmation: It requires a final prompt_confirm before performing any fs::write operations.

Sources: src/init.rs:55-73, tests/init.rs:109-125

Usage and Constraints

The wizard is accessed via cargo cooldown init. It is strictly a configuration tool and is distinct from Cargo's own cargo init.

• Execution Location: It must be run from a directory containing a Cargo.toml. Running it outside a project root results in an error.
• Argument Handling: It does not accept standard Cargo selection flags (like --manifest-path) when running the init command.
• Collision with Cargo: If the user attempts to pass flags like --bin to cargo cooldown init, the tool identifies the likely confusion with cargo init and provides a specific explanatory error.

Sources: src/main.rs:136-144, tests/init.rs:132-142, tests/cli.rs:10-25

Conclusion

The Initialization Wizard simplifies the adoption of cargo-cooldown by providing a guided interface for creating project-specific safety policies. By automating the generation of cooldown.toml and offering workspace-aware configuration, it ensures that users can quickly establish a security baseline for their Rust dependencies.