gammaloop_api/

session.rs

//! Borrowed command-session access to a loaded GammaLoop state.
//!
//! [`CliSession`] ties together the domain state, replay history, persistent settings, runtime
//! defaults, and transient command-block state owned by [`crate::LoadedState`]. It does not own or
//! automatically persist any of them.

use std::{
    collections::BTreeMap,
    io::{self, IsTerminal, Write},
    ops::ControlFlow,
};

use color_eyre::{eyre::eyre, Result};
use colored::Colorize;
use gammalooprs::integrands::process::ProcessIntegrand;
use gammalooprs::model::Model;
use gammalooprs::processes::{
    GraphSelectionSignatureInventory, ProcessCollection, ProcessDefinition,
    RaisedCutSignatureInventory,
};
use gammalooprs::settings::{global::GenerationSettings, RuntimeSettings};
use tracing::{info, warn};

use crate::{
    command_template::contains_placeholder,
    commands::{
        run::{
            prepare_command_histories_with_context, PreparedCommand, PreparedRun, MAX_RUN_DEPTH,
        },
        save::SaveState,
        CommandExecution, Commands, StartCommandsBlock,
    },
    completion::{
        IntegrandDetailCompletionEntry, IrProfileCompletionEntry, ModelVertexCompletionEntry,
        ProcessCompletionEntry, ProcessKind,
    },
    integrand_info::IntegrandKind,
    render_smart_toml,
    state::{CommandHistory, CommandsBlock, ProcessRef, RunHistory, State},
    CLISettings, ReadOnlyStateOrigin,
};

#[cfg(feature = "cli")]
use crate::commands::process_settings::{
    serialize_runtime_named_settings, ProcessSettingsCompletionEntry,
};

const MAX_DISPLAY_COMMAND_LINES: usize = 5;

fn format_command_block_conflict_message(conflicting_blocks: &[String]) -> String {
    match conflicting_blocks {
        [] => String::new(),
        [single] => format!(
            "Run card command block '{}' redefines an existing block with different commands",
            single
        ),
        many => format!(
            "Run card command blocks {} redefine existing blocks with different commands",
            many.iter()
                .map(|name| format!("'{}'", name))
                .collect::<Vec<_>>()
                .join(", ")
        ),
    }
}

fn prompt_command_block_conflict_override(conflicting_blocks: &[String]) -> Result<bool> {
    let prompt = format!(
        "{}. Proceed anyway? (it may break reproducibility of the state from run.toml) [y/n] > ",
        format_command_block_conflict_message(conflicting_blocks)
    );
    let mut stderr = io::stderr();
    let mut input = String::new();
    loop {
        eprint!("{prompt}");
        stderr.flush()?;
        input.clear();
        io::stdin().read_line(&mut input)?;
        match input.trim().to_ascii_lowercase().as_str() {
            "y" | "yes" => return Ok(true),
            "n" | "no" => return Ok(false),
            _ => {
                eprintln!("Please answer 'y' or 'n'.");
            }
        }
    }
}

/// Transient state used while defining a reusable command block.
///
/// This is process/session state rather than persisted run history. Most callers should retain the
/// value inside [`crate::LoadedState`] and access it through [`CliSession`].
#[derive(Debug, Clone, Default)]
pub struct CliSessionState {
    pending_commands_block: Option<PendingCommandsBlock>,
}

#[derive(Debug, Clone)]
struct PendingCommandsBlock {
    name: String,
    commands: Vec<CommandHistory>,
}

#[derive(Debug, Clone, Copy, PartialEq, Eq)]
enum HistoryMode {
    Record,
    Suppress,
}

/// Mutably borrowed view used to execute GammaLoop commands.
///
/// A session updates its caller-owned [`State`], [`RunHistory`], and effective settings in place.
/// It may also write files according to the selected command. Read-only mode prevents
/// GammaLoop-managed writes into the active state tree, but does not constrain explicit exports or
/// external processes such as the `!` shell command.
pub struct CliSession<'a> {
    state: &'a mut State,
    run_history: &'a mut RunHistory,
    cli_settings: &'a mut CLISettings,
    default_runtime_settings: &'a mut RuntimeSettings,
    session_state: &'a mut CliSessionState,
}

impl<'a> CliSession<'a> {
    /// Combine the mutable state and settings that participate in command execution.
    ///
    /// This constructor does not initialize GammaLoop, load files, replay history, or execute boot
    /// commands. Prefer [`crate::StateLoadOption::load`] followed by
    /// [`crate::LoadedState::cli_session`] unless the caller already owns a consistent bundle.
    pub fn new(
        state: &'a mut State,
        run_history: &'a mut RunHistory,
        cli_settings: &'a mut CLISettings,
        default_runtime_settings: &'a mut RuntimeSettings,
        session_state: &'a mut CliSessionState,
    ) -> Self {
        Self {
            state,
            run_history,
            cli_settings,
            default_runtime_settings,
            session_state,
        }
    }

    /// Prepare and execute one command against the borrowed state.
    ///
    /// Ordinary successful commands are normalized and appended to the replayable run history;
    /// command-block definition controls have specialized recording behavior. A command can mutate
    /// the state and settings or write its requested outputs before returning. Inspect both
    /// [`CommandExecution::flow`] and [`CommandExecution::output`]: save/quit requests use
    /// [`ControlFlow::Break`], while only evaluation and integration currently return structured
    /// output.
    ///
    /// Errors include parse/preparation failures, invalid state or settings, unavailable backends,
    /// numerical command failures, and forbidden writes into a read-only state tree. An error does
    /// not imply that every command-specific external effect was rolled back.
    pub fn execute_command(&mut self, command: CommandHistory) -> Result<CommandExecution> {
        let prepared = PreparedCommand::prepare(command, self.run_history, 1)?;
        self.execute_prepared(prepared, HistoryMode::Record)
    }

    /// Reapply the stored session settings and commands without appending duplicate history.
    ///
    /// Replay mutates the current state and can perform the same command-specific effects as normal
    /// execution. Callers must honor a returned [`ControlFlow::Break`] save/quit request.
    pub fn replay_run_history(&mut self) -> Result<ControlFlow<SaveState>> {
        self.run_history
            .apply_session_settings(self.cli_settings, self.default_runtime_settings)?;
        let prepared = prepare_command_histories_with_context(
            &self.run_history.commands.clone(),
            self.run_history,
            1,
            "run history",
        )?;
        self.execute_prepared_commands(prepared, HistoryMode::Suppress)
    }

    pub fn apply_boot_run_history(
        &mut self,
        boot_run_history: &RunHistory,
        effective_boot_run_history: &RunHistory,
        booted_existing_state: bool,
    ) -> Result<ControlFlow<SaveState>> {
        let interactive_prompt_available = io::stdin().is_terminal() && io::stdout().is_terminal();
        self.apply_boot_run_history_with_conflict_resolver(
            boot_run_history,
            effective_boot_run_history,
            booted_existing_state,
            |conflicting_blocks| {
                if interactive_prompt_available {
                    return prompt_command_block_conflict_override(conflicting_blocks);
                }

                Err(eyre!(
                    "{}. Cannot continue non-interactively; rerun in an interactive terminal or align the command block definitions.",
                    format_command_block_conflict_message(conflicting_blocks)
                ))
            },
        )
    }

    pub fn apply_boot_run_history_with_conflict_resolver<F>(
        &mut self,
        boot_run_history: &RunHistory,
        effective_boot_run_history: &RunHistory,
        booted_existing_state: bool,
        mut resolve_conflicts: F,
    ) -> Result<ControlFlow<SaveState>>
    where
        F: FnMut(&[String]) -> Result<bool>,
    {
        boot_run_history.validate()?;

        if booted_existing_state
            && !self
                .run_history
                .frozen_boot_settings_match(boot_run_history)
        {
            let warning = format!(
                "Boot card settings differ from the frozen settings stored in {}. This session is forced into --read-only-state. Line up cli_settings.global and default_runtime_settings in the boot card with the frozen settings in run.toml if you want to boot this state without read-only mode.",
                self.cli_settings.state.folder.join("run.toml").display()
            );
            self.cli_settings
                .session
                .force_read_only_state(ReadOnlyStateOrigin::BootSettingsMismatch);
            self.cli_settings
                .session
                .startup_warnings
                .push(warning.clone());
            warn!("{warning}");
        }
        if !booted_existing_state {
            self.run_history.freeze_boot_settings_from(boot_run_history);
        }

        let mut merged_history = self.run_history.clone();
        let conflicting_blocks = merged_history
            .conflicting_command_block_names(&effective_boot_run_history.command_blocks);
        let overwrite_conflicting_blocks = if conflicting_blocks.is_empty() {
            false
        } else if self.cli_settings.session.read_only_state {
            if self
                .cli_settings
                .session
                .is_read_only_due_to_boot_settings_mismatch()
            {
                let warning = format!(
                    "{}. The boot card settings differ from the frozen settings stored in {}; this session remains in --read-only-state for reproducibility, but will use the boot card command block definitions for this process only.",
                    format_command_block_conflict_message(&conflicting_blocks),
                    self.cli_settings.state.folder.join("run.toml").display()
                );
                self.cli_settings
                    .session
                    .startup_warnings
                    .push(warning.clone());
                warn!("{warning}");
                true
            } else {
                return Err(eyre!(
                    "{}. Cannot proceed while --read-only-state is enabled.",
                    format_command_block_conflict_message(&conflicting_blocks)
                ));
            }
        } else if resolve_conflicts(&conflicting_blocks)? {
            true
        } else {
            info!(
                "{}",
                "Boot run card application cancelled by user.".yellow()
            );
            return Ok(ControlFlow::Break(SaveState::default()));
        };
        merged_history.merge_command_blocks_with_overwrite(
            &effective_boot_run_history.command_blocks,
            overwrite_conflicting_blocks,
        )?;

        for block in &effective_boot_run_history.command_blocks {
            // Reusable blocks may inherit variables through nested runs. Validate
            // names and recursion without expanding those variables; expansion
            // uses the actual invocation environment before any command executes.
            let mut pending = vec![(
                format!("command block '{}'", block.name),
                block.commands.clone(),
                vec![block.name.clone()],
                2,
            )];
            while let Some((context, commands, active_blocks, depth)) = pending.pop() {
                for (index, command) in commands.into_iter().enumerate() {
                    let Commands::Run(run) = command.command else {
                        continue;
                    };
                    if depth > MAX_RUN_DEPTH {
                        return Err(eyre!(
                            "Maximum nested run depth of {} reached while validating {}",
                            MAX_RUN_DEPTH,
                            context
                        ));
                    }
                    let names = run
                        .selected_block_names()
                        .iter()
                        .filter(|name| !contains_placeholder(name))
                        .cloned()
                        .collect::<Vec<_>>();
                    let selected = merged_history
                        .select_command_blocks(&names)
                        .map_err(|err| {
                            eyre!(
                                "Failed to validate {} command #{}: {}",
                                context,
                                index + 1,
                                err
                            )
                        })?;
                    for nested in selected.into_iter().rev() {
                        if let Some(start) =
                            active_blocks.iter().position(|name| *name == nested.name)
                        {
                            let mut cycle = active_blocks[start..].to_vec();
                            cycle.push(nested.name.clone());
                            return Err(eyre!(
                                "Command block recursion detected: {}",
                                cycle.join(" -> ")
                            ));
                        }
                        let mut active = active_blocks.clone();
                        active.push(nested.name.clone());
                        pending.push((
                            format!("command block '{}'", nested.name),
                            nested.commands,
                            active,
                            depth + 1,
                        ));
                    }
                    let inline = run.parse_inline_commands()?;
                    if !inline.is_empty() {
                        pending.push((
                            format!("{} run -c", context),
                            inline,
                            active_blocks.clone(),
                            depth + 1,
                        ));
                    }
                }
            }
        }

        let prepared = prepare_command_histories_with_context(
            &effective_boot_run_history.commands,
            &merged_history,
            1,
            "boot",
        )?;

        self.run_history.merge_command_blocks_with_overwrite(
            &effective_boot_run_history.command_blocks,
            overwrite_conflicting_blocks,
        )?;
        effective_boot_run_history
            .apply_session_settings(self.cli_settings, self.default_runtime_settings)?;
        self.execute_prepared_commands(prepared, HistoryMode::Record)
    }

    pub fn has_pending_commands_block(&self) -> bool {
        self.session_state.pending_commands_block.is_some()
    }

    pub fn pending_commands_block_name(&self) -> Option<String> {
        self.session_state
            .pending_commands_block
            .as_ref()
            .map(|pending| pending.name.clone())
    }

    pub fn prompt_state_label(&self) -> String {
        self.cli_settings.state.prompt_label()
    }

    pub fn current_commands_block_names(&self) -> Vec<String> {
        self.run_history
            .command_blocks
            .iter()
            .map(|block| block.name.clone())
            .collect()
    }

    pub fn current_command_block_placeholders(
        &self,
    ) -> BTreeMap<String, Vec<crate::command_template::PlaceholderSpec>> {
        self.run_history
            .command_blocks
            .iter()
            .map(|block| {
                (
                    block.name.clone(),
                    self.run_history
                        .command_block_placeholder_specs(&block.name)
                        .into_iter()
                        .collect(),
                )
            })
            .collect()
    }

    pub fn current_process_entries(&self) -> Vec<ProcessCompletionEntry> {
        self.state
            .process_list
            .processes
            .iter()
            .enumerate()
            .map(|(id, process)| ProcessCompletionEntry {
                id,
                name: process.definition.folder_name.clone(),
                kind: match &process.collection {
                    ProcessCollection::Amplitudes(_) => ProcessKind::Amplitude,
                    ProcessCollection::CrossSections(_) => ProcessKind::CrossSection,
                },
                integrand_names: process
                    .collection
                    .get_integrand_names()
                    .into_iter()
                    .map(str::to_string)
                    .collect(),
            })
            .collect()
    }

    pub fn current_integrand_detail_entries(&self) -> Vec<IntegrandDetailCompletionEntry> {
        self.state
            .process_list
            .processes
            .iter()
            .enumerate()
            .flat_map(|(process_id, process)| {
                process
                    .collection
                    .get_integrand_names()
                    .into_iter()
                    .filter_map(move |integrand_name| {
                        let integrand_name = integrand_name.to_string();
                        let info = self
                            .state
                            .get_integrand_info(
                                Some(&ProcessRef::Id(process_id)),
                                Some(&integrand_name),
                            )
                            .ok()?;
                        let mut master_graph_names = info
                            .graph_groups
                            .iter()
                            .filter_map(|group| {
                                group
                                    .graphs
                                    .iter()
                                    .find(|graph| graph.is_master)
                                    .map(|graph| graph.name.clone())
                            })
                            .collect::<Vec<_>>();
                        master_graph_names.sort();
                        master_graph_names.dedup();

                        let mut categories = vec![
                            "generation".to_string(),
                            "orientation".to_string(),
                            "loop_momentum_basis".to_string(),
                        ];
                        if info.kind == IntegrandKind::CrossSection {
                            categories.push("cuts".to_string());
                        }
                        let signature_inventory =
                            integrand_signature_inventory(&process.collection, &integrand_name);
                        let amplitude_signature_inventory = amplitude_graph_signature_inventory(
                            &process.collection,
                            &integrand_name,
                            &self.state.model,
                            &process.definition,
                            &self.cli_settings.global.generation,
                        );
                        let raised_cut_signature_inventory = raised_cut_signature_inventory(
                            &process.collection,
                            &integrand_name,
                            &self.state.model,
                            &process.definition,
                            &self.cli_settings.global.generation,
                        );

                        Some(IntegrandDetailCompletionEntry {
                            process_name: process.definition.folder_name.clone(),
                            integrand_name,
                            kind: info.kind,
                            master_graph_names,
                            raised_all_signatures: signature_inventory.raised_all,
                            raised_massive_signatures: signature_inventory.raised_massive,
                            raised_massless_signatures: signature_inventory.raised_massless,
                            cycle_signatures: signature_inventory.cycles,
                            amplitude_raised_all_signatures: amplitude_signature_inventory
                                .raised_all,
                            amplitude_raised_massive_signatures: amplitude_signature_inventory
                                .raised_massive,
                            amplitude_raised_massless_signatures: amplitude_signature_inventory
                                .raised_massless,
                            amplitude_cycle_signatures: amplitude_signature_inventory.cycles,
                            raised_cut_all_signatures: raised_cut_signature_inventory.all,
                            raised_cut_massive_signatures: raised_cut_signature_inventory.massive,
                            raised_cut_massless_signatures: raised_cut_signature_inventory.massless,
                            categories,
                        })
                    })
                    .collect::<Vec<_>>()
            })
            .collect()
    }

    pub fn current_ir_profile_entries(&self) -> Vec<IrProfileCompletionEntry> {
        self.state
            .process_list
            .processes
            .iter()
            .filter_map(|process| {
                let ProcessCollection::CrossSections(cross_sections) = &process.collection else {
                    return None;
                };

                Some(
                    cross_sections
                        .iter()
                        .filter_map(|(integrand_name, cross_section)| {
                            let ProcessIntegrand::CrossSection(integrand) =
                                cross_section.integrand.as_ref()?
                            else {
                                return None;
                            };
                            let completion_entries = integrand.ir_profile_completion_entries();
                            let mut graph_names = completion_entries
                                .iter()
                                .map(|(graph_name, _)| graph_name.clone())
                                .collect::<Vec<_>>();
                            graph_names.sort();
                            graph_names.dedup();

                            let mut graph_limit_entries = completion_entries
                                .into_iter()
                                .flat_map(|(graph_name, limits)| {
                                    limits
                                        .into_iter()
                                        .map(move |limit| format!("{graph_name} {limit}"))
                                })
                                .collect::<Vec<_>>();
                            graph_limit_entries.sort();
                            graph_limit_entries.dedup();

                            Some(IrProfileCompletionEntry {
                                process_name: process.definition.folder_name.clone(),
                                integrand_name: integrand_name.clone(),
                                graph_names,
                                graph_limit_entries,
                            })
                        })
                        .collect::<Vec<_>>(),
                )
            })
            .flatten()
            .collect()
    }

    #[cfg(feature = "cli")]
    pub(crate) fn current_process_settings_entries(&self) -> Vec<ProcessSettingsCompletionEntry> {
        let mut entries = Vec::new();

        for (process_id, process) in self.state.process_list.processes.iter().enumerate() {
            for integrand_name in process.collection.get_integrand_names() {
                let Ok(resolved) = process.get_integrand(integrand_name) else {
                    continue;
                };
                let Some(integrand) = resolved.integrand else {
                    continue;
                };
                let Ok(serialized) = serialize_runtime_named_settings(integrand.get_settings())
                else {
                    continue;
                };

                entries.push(ProcessSettingsCompletionEntry {
                    process_id,
                    process_name: process.definition.folder_name.clone(),
                    integrand_name: integrand_name.to_string(),
                    quantities: serialized.quantities,
                    observables: serialized.observables,
                    selectors: serialized.selectors,
                });
            }
        }

        entries.sort_by(|left, right| {
            left.process_id
                .cmp(&right.process_id)
                .then_with(|| left.integrand_name.cmp(&right.integrand_name))
        });
        entries
    }

    pub fn current_model_parameter_entries(
        &self,
    ) -> Vec<crate::completion::ModelParameterCompletionEntry> {
        let mut entries = self
            .state
            .model_parameters
            .keys()
            .filter_map(|name| {
                self.state
                    .model
                    .get_parameter_opt(name.to_string())
                    .map(
                        |parameter| crate::completion::ModelParameterCompletionEntry {
                            name: name.to_string(),
                            parameter_type: parameter.parameter_type.clone(),
                        },
                    )
            })
            .collect::<Vec<_>>();
        entries.sort_by(|left, right| left.name.cmp(&right.name));
        entries
    }

    pub fn current_model_particle_names(&self) -> Vec<String> {
        let mut names = self
            .state
            .model
            .particles
            .iter()
            .flat_map(|particle| [particle.name.to_string(), particle.antiname.to_string()])
            .collect::<Vec<_>>();
        names.sort();
        names.dedup();
        names
    }

    pub fn current_model_select_particle_names(&self) -> Vec<String> {
        let mut names = self
            .state
            .model
            .particles
            .iter()
            .filter(|particle| particle.pdg_code > 0)
            .map(|particle| particle.name.to_string())
            .collect::<Vec<_>>();
        names.sort();
        names.dedup();
        names
    }

    pub fn current_model_coupling_names(&self) -> Vec<String> {
        let mut names = self
            .state
            .model
            .orders
            .iter()
            .map(|order| order.name.to_string())
            .collect::<Vec<_>>();
        names.sort();
        names.dedup();
        names
    }

    pub fn current_model_vertices(&self) -> Vec<ModelVertexCompletionEntry> {
        let mut entries = self
            .state
            .model
            .vertex_rules
            .iter()
            .map(|vertex_rule| ModelVertexCompletionEntry {
                name: vertex_rule.0.name.to_string(),
                particles: vertex_rule
                    .0
                    .particles
                    .iter()
                    .map(|particle| particle.name.to_string())
                    .collect(),
            })
            .collect::<Vec<_>>();
        entries.sort_by(|left, right| left.name.cmp(&right.name));
        entries.dedup_by(|left, right| left.name == right.name);
        entries
    }

    pub fn run_history_toml(&self) -> Result<String> {
        self.run_history
            .to_toml_string(self.cli_settings.try_strings)
    }

    pub fn global_settings_toml(&self) -> Result<String> {
        render_smart_toml(self.cli_settings)
    }

    pub fn active_command_blocks(&self) -> BTreeMap<String, Vec<String>> {
        self.run_history
            .command_blocks
            .iter()
            .map(|block| {
                (
                    block.name.clone(),
                    block.commands.iter().map(display_command).collect(),
                )
            })
            .collect()
    }

    pub fn dismiss_pending_commands_block(&mut self, trigger: &str) -> bool {
        let Some(pending) = self.session_state.pending_commands_block.take() else {
            return false;
        };

        info!(
            "{} {} {} {}",
            "Dismissing command block definition".blue(),
            pending.name.green(),
            "after".blue(),
            trigger.green()
        );
        true
    }

    fn execute_prepared_commands(
        &mut self,
        commands: Vec<PreparedCommand>,
        history_mode: HistoryMode,
    ) -> Result<ControlFlow<SaveState>> {
        for command in commands {
            let execution = self.execute_prepared(command, history_mode)?;
            if let ControlFlow::Break(save_state) = execution.flow {
                return Ok(ControlFlow::Break(save_state));
            }
        }
        Ok(ControlFlow::Continue(()))
    }

    fn execute_prepared(
        &mut self,
        command: PreparedCommand,
        history_mode: HistoryMode,
    ) -> Result<CommandExecution> {
        match command {
            PreparedCommand::Plain(command) => self.execute_plain(command, history_mode),
            PreparedCommand::Run { command, plan } => self.execute_run(command, plan, history_mode),
        }
    }

    fn execute_plain(
        &mut self,
        command: CommandHistory,
        history_mode: HistoryMode,
    ) -> Result<CommandExecution> {
        if self.session_state.pending_commands_block.is_some() {
            return self.handle_recording_mode(command);
        }

        let display_text = display_command(&command);
        info!("{} {}", "Running command".blue(), display_text.green());

        let record = match &command.command {
            Commands::StartCommandsBlock(start) => {
                self.start_commands_block(start.clone())?;
                false
            }
            Commands::FinishCommandsBlock => {
                self.finish_commands_block()?;
                false
            }
            _ => {
                let execution = command.command.clone().run(
                    self.state,
                    self.run_history,
                    self.cli_settings,
                    self.default_runtime_settings,
                )?;
                if let ControlFlow::Break(save_state) = execution.flow {
                    if history_mode == HistoryMode::Record {
                        self.record_command(&command);
                    }
                    return Ok(CommandExecution::break_with(save_state));
                }
                let output = execution.output;
                if history_mode == HistoryMode::Record {
                    self.record_command(&command);
                }
                return Ok(CommandExecution::continue_with(output));
            }
        };

        if record {
            self.record_command(&command);
        }

        Ok(CommandExecution::continue_without_output())
    }

    fn execute_run(
        &mut self,
        command: CommandHistory,
        plan: PreparedRun,
        history_mode: HistoryMode,
    ) -> Result<CommandExecution> {
        if self.session_state.pending_commands_block.is_some() {
            return self.handle_recording_mode(command);
        }

        if plan.is_empty() {
            return Ok(CommandExecution::continue_without_output());
        }

        let display_text = display_command(&command);
        info!("{} {}", "Running command".blue(), display_text.green());

        for block in plan.blocks {
            info!("{} {}", "Starting command block".blue(), block.name.green());
            if let ControlFlow::Break(save_state) =
                self.execute_prepared_commands(block.commands, HistoryMode::Suppress)?
            {
                if history_mode == HistoryMode::Record {
                    self.record_command(&command);
                }
                return Ok(CommandExecution::break_with(save_state));
            }
        }

        if !plan.commands.is_empty() {
            info!(
                "{} {}",
                "Starting commands supplied with".blue(),
                "--commands/-c".green()
            );
        }

        if let ControlFlow::Break(save_state) =
            self.execute_prepared_commands(plan.commands, HistoryMode::Suppress)?
        {
            if history_mode == HistoryMode::Record {
                self.record_command(&command);
            }
            return Ok(CommandExecution::break_with(save_state));
        }

        if history_mode == HistoryMode::Record {
            self.record_command(&command);
        }

        Ok(CommandExecution::continue_without_output())
    }

    fn handle_recording_mode(&mut self, command: CommandHistory) -> Result<CommandExecution> {
        match command.command.clone() {
            Commands::StartCommandsBlock(_) => Err(eyre!(
                "Cannot start a new command block definition before finishing the current one"
            )),
            Commands::FinishCommandsBlock => {
                self.finish_commands_block()?;
                Ok(CommandExecution::continue_without_output())
            }
            Commands::Quit(_) => {
                self.dismiss_pending_commands_block("quit");
                Ok(CommandExecution::continue_without_output())
            }
            _ => {
                let stored = normalize_command_history(&command);
                let pending = self
                    .session_state
                    .pending_commands_block
                    .as_mut()
                    .expect("recording mode requires a pending block");
                pending.commands.push(stored);
                Ok(CommandExecution::continue_without_output())
            }
        }
    }

    fn start_commands_block(&mut self, start: StartCommandsBlock) -> Result<()> {
        if self.session_state.pending_commands_block.is_some() {
            return Err(eyre!(
                "Cannot start a new command block definition before finishing the current one"
            ));
        }

        if self.run_history.command_block(&start.name).is_some() {
            info!(
                "{} {}",
                "Overwriting existing command block definition".blue(),
                start.name.green()
            );
        } else {
            info!(
                "{} {}",
                "Defining new command block definition".blue(),
                start.name.green()
            );
        }

        self.session_state.pending_commands_block = Some(PendingCommandsBlock {
            name: start.name,
            commands: Vec::new(),
        });
        Ok(())
    }

    fn finish_commands_block(&mut self) -> Result<()> {
        let Some(pending) = self.session_state.pending_commands_block.take() else {
            return Err(eyre!(
                "No command block definition is currently being recorded"
            ));
        };

        let block = CommandsBlock {
            name: pending.name.clone(),
            commands: pending.commands,
        };

        if let Some(existing_index) = self
            .run_history
            .command_blocks
            .iter()
            .position(|existing| existing.name == pending.name)
        {
            self.run_history.command_blocks[existing_index] = block;
        } else {
            self.run_history.command_blocks.push(block);
        }

        self.run_history.validate()?;
        Ok(())
    }

    fn record_command(&mut self, command: &CommandHistory) {
        if let Some(normalized) = normalize_persisted_command_history(command) {
            self.run_history
                .push_with_raw(normalized.command, normalized.raw_string);
        }
    }
}

fn integrand_signature_inventory(
    collection: &ProcessCollection,
    integrand_name: &str,
) -> GraphSelectionSignatureInventory {
    match collection {
        ProcessCollection::Amplitudes(amplitudes) => amplitudes
            .get(integrand_name)
            .map(|amplitude| {
                GraphSelectionSignatureInventory::from_master_graphs(
                    amplitude.graph_group_structure.iter().map(|group| {
                        let master_graph_id = group
                            .into_iter()
                            .next()
                            .expect("graph group should contain a master graph");
                        &amplitude.graphs[master_graph_id].graph
                    }),
                )
            })
            .unwrap_or_else(GraphSelectionSignatureInventory::empty),
        ProcessCollection::CrossSections(cross_sections) => cross_sections
            .get(integrand_name)
            .map(|cross_section| {
                GraphSelectionSignatureInventory::from_master_graphs(
                    cross_section.graph_group_structure.iter().map(|group| {
                        let master_graph_id = group
                            .into_iter()
                            .next()
                            .expect("graph group should contain a master graph");
                        &cross_section.supergraphs[master_graph_id].graph
                    }),
                )
            })
            .unwrap_or_else(GraphSelectionSignatureInventory::empty),
    }
}

fn amplitude_graph_signature_inventory(
    collection: &ProcessCollection,
    integrand_name: &str,
    model: &Model,
    process_definition: &ProcessDefinition,
    generation_settings: &GenerationSettings,
) -> GraphSelectionSignatureInventory {
    let ProcessCollection::CrossSections(cross_sections) = collection else {
        return GraphSelectionSignatureInventory::empty();
    };
    cross_sections
        .get(integrand_name)
        .map(|cross_section| {
            cross_section
                .amplitude_graph_signature_inventory(model, process_definition, generation_settings)
                .unwrap_or_else(|_| GraphSelectionSignatureInventory::empty())
        })
        .unwrap_or_else(GraphSelectionSignatureInventory::empty)
}

fn raised_cut_signature_inventory(
    collection: &ProcessCollection,
    integrand_name: &str,
    model: &Model,
    process_definition: &ProcessDefinition,
    generation_settings: &GenerationSettings,
) -> RaisedCutSignatureInventory {
    let ProcessCollection::CrossSections(cross_sections) = collection else {
        return RaisedCutSignatureInventory::empty();
    };
    cross_sections
        .get(integrand_name)
        .map(|cross_section| {
            cross_section
                .raised_cut_signature_inventory(model, process_definition, generation_settings)
                .unwrap_or_else(|_| RaisedCutSignatureInventory::empty())
        })
        .unwrap_or_else(RaisedCutSignatureInventory::empty)
}

fn normalize_persisted_command_history(command: &CommandHistory) -> Option<CommandHistory> {
    match &command.command {
        Commands::Quit(_) | Commands::StartCommandsBlock(_) | Commands::FinishCommandsBlock => None,
        Commands::Run(run) => normalize_persisted_run_history(command, run),
        _ => Some(normalize_command_history(command)),
    }
}

fn normalize_persisted_run_history(
    command: &CommandHistory,
    run: &crate::commands::Run,
) -> Option<CommandHistory> {
    let inline_commands = run
        .parse_inline_commands()
        .expect("persisted run commands should always have parseable inline commands");
    let persisted_inline_commands = inline_commands
        .iter()
        .filter_map(normalize_persisted_command_history)
        .collect::<Vec<_>>();

    let persisted_run = crate::commands::Run {
        block_names: run.block_names.clone(),
        defines: run.defines.clone(),
        commands: (!persisted_inline_commands.is_empty()).then(|| {
            persisted_inline_commands
                .iter()
                .map(persisted_command_raw_string)
                .collect::<Vec<_>>()
                .join("; ")
        }),
    };

    if persisted_run.is_noop() {
        return None;
    }

    if persisted_run == *run {
        return Some(normalize_command_history(command));
    }

    let raw_string = persisted_run.canonical_raw_string();
    Some(CommandHistory::new_with_raw(
        Commands::Run(persisted_run),
        raw_string,
    ))
}

fn persisted_command_raw_string(command: &CommandHistory) -> String {
    normalize_command_history(command)
        .raw_string()
        .expect("persisted inline commands should remain representable as raw strings")
        .to_string()
}

fn normalize_command_history(command: &CommandHistory) -> CommandHistory {
    let raw_string = command
        .raw_string()
        .filter(|raw| raw_round_trips(raw, &command.command))
        .map(str::to_string)
        .or_else(|| match &command.command {
            Commands::Run(run) => Some(run.canonical_raw_string()),
            _ => None,
        });

    CommandHistory {
        command: command.command.clone(),
        raw_string,
    }
}

fn raw_round_trips(raw: &str, command: &Commands) -> bool {
    CommandHistory::from_raw_string(raw)
        .map(|parsed| parsed.command == *command)
        .unwrap_or(false)
}

pub(crate) fn display_command(command: &CommandHistory) -> String {
    let display = if let Some(raw_string) = normalize_command_history(command).raw_string {
        raw_string
    } else {
        format!("{:?}", command.command)
    };

    truncate_multiline_display_command(&display)
}

fn truncate_multiline_display_command(display: &str) -> String {
    let lines = display.lines().collect::<Vec<_>>();
    if lines.len() <= MAX_DISPLAY_COMMAND_LINES {
        return display.to_string();
    }

    let mut truncated = lines[..MAX_DISPLAY_COMMAND_LINES].join("\n");
    truncated.push_str("\n[...]");
    truncated
}

#[cfg(test)]
mod tests {
    use super::{display_command, MAX_DISPLAY_COMMAND_LINES};
    use crate::{commands::run::Run, commands::Commands, state::CommandHistory};

    #[test]
    fn display_command_preserves_multiline_commands_up_to_line_limit() {
        let commands = (1..=MAX_DISPLAY_COMMAND_LINES)
            .map(|i| format!("cmd{i}"))
            .collect::<Vec<_>>()
            .join("\n");
        let command = CommandHistory::new(Commands::Run(Run {
            block_names: Vec::new(),
            defines: Vec::new(),
            commands: Some(commands.clone()),
        }));

        let displayed = display_command(&command);

        assert_eq!(displayed.lines().count(), MAX_DISPLAY_COMMAND_LINES);
        assert!(displayed.contains(&commands));
        assert!(!displayed.contains("[...]"));
    }

    #[test]
    fn display_command_truncates_multiline_commands_beyond_line_limit() {
        let command = CommandHistory::new(Commands::Run(Run {
            block_names: Vec::new(),
            defines: Vec::new(),
            commands: Some("cmd1\ncmd2\ncmd3\ncmd4\ncmd5\ncmd6".to_string()),
        }));

        let displayed = display_command(&command);
        let displayed_lines = displayed.lines().collect::<Vec<_>>();

        assert_eq!(
            displayed_lines,
            vec!["run -c 'cmd1", "cmd2", "cmd3", "cmd4", "cmd5", "[...]"]
        );
    }
}