Description:

Implement the user-facing Command Line Interface (CLI) for the SCREAM++ application, focusing initially on the core place subcommand. This CLI will serve as the primary entry point for users to interact with the scream-core library. It will be responsible for parsing command-line arguments, loading configuration files, executing the main placement workflow, providing user feedback via progress indicators, and handling the writing of output files.

Tasks:

• CLI Argument & Command Structure (cli.rs)

  • Define Top-Level Cli Struct: Create the main Cli struct using clap::Parser to define the application's version, author, and overall help message.
  • Define Commands Enum: Implement a subcommand enum to house all future commands (Place, Design, Analyze).
  • Define PlaceArgs Struct: Create a struct for the place subcommand to define its specific arguments:
    • --input/-i: Path to the input structure file.
    • --output/-o: Path for the output structure file.
    • --config/-c: Path to the workflow configuration TOML file.
    • --force: A boolean flag to allow overwriting existing output files.
  • Add Rich Help Messages: Use doc comments (///) on all structs and fields to ensure clap generates comprehensive and user-friendly help text for scream --help and scream place --help.

• Configuration Loading (config.rs)

  • Implement load_placement_config Function: Create a dedicated function to handle the loading and parsing of the user-provided TOML configuration file.
  • Define File-Specific Structs: Use serde::Deserialize to create temporary structs that exactly match the TOML file's structure.
  • Convert to Core Config: Use the screampp::engine::config::PlacementConfigBuilder to convert the parsed TOML data into the PlacementConfig struct required by the scream-core library, providing clear error messages for missing or malformed fields.

• Workflow Execution Logic (commands/place.rs)

  • Implement execute Function: Create the main logic function that takes PlaceArgs as input.
  • Orchestrate Workflow: The function will perform the following steps in sequence:
    • Load the PlacementConfig using the config.rs module.
    • Load the input MolecularSystem using the scream-core::io module (e.g., BgfFile).
    • Set up a ProgressReporter and connect its callback to an indicatif ProgressBar to provide real-time visual feedback to the user.
    • Call the screampp::workflows::place::run() function with the loaded system, config, and reporter.
    • Process the Result: handle success by saving the best Solution's system to the specified output file, and handle errors by propagating them up.
  • Handle File I/O: Check if the output file exists and respect the --force flag.

• Error Handling & Main Entry Point (error.rs, main.rs)

  • Define CliError Enum: Create a custom, user-facing error enum using thiserror. This enum will unify errors from different sources (I/O, TOML parsing, scream-core engine) into a single type.
  • Implement #[from] Trait: Use #[from] to enable automatic conversion from underlying error types (std::io::Error, toml::de::Error, screampp::engine::error::EngineError) into CliError.
  • Implement main.rs: Keep the main function clean. It should only parse the CLI arguments and dispatch to the appropriate command's execute function, wrapping the call in a top-level error handler that prints a user-friendly message upon failure.