Foundry UI (#3392)

<!-- Reference any GitHub issues resolved by this PR -->

Towards #3022

**Stack**:
- #3409
- #3405
- #3402
- #3396
- #3393
- #3392 ⬅


## Introduced changes

- Introduce `foundry-ui` crate
    - Add `UI`, `Message`

## Checklist

<!-- Make sure all of these are complete -->

- [x] Linked relevant issue
- [x] Updated relevant documentation
- [x] Added relevant tests
- [x] Performed self-review of the code
- [x] Added changes to `CHANGELOG.md`

Author: franciszekjob

Cargo.lock

@@ -16,6 +16,7 @@ members = [
     "crates/docs",
     "crates/debugging",
     "crates/testing/packages_validation",
+    "crates/foundry-ui",
 ]
 
 exclude = ["crates/snforge-scarb-plugin"]

Cargo.toml

@@ -71,6 +71,7 @@ pub fn maybe_save_trace_and_profile(
             let name = sanitize_filename::sanitize(name.replace("::", "_"));
             let trace_path = save_trace_data(&name, trace_data)?;
             if execution_data_to_save.profile {
+                // TODO(#3395): Use Ui spinner
                 let _spinner = Spinner::create_with_message("Running cairo-profiler");
                 run_profiler(&name, &trace_path, &execution_data_to_save.additional_args)?;
             }
@@ -88,6 +89,7 @@ pub fn maybe_generate_coverage(
         if saved_trace_data_paths.is_empty() {
             print_as_warning(&anyhow!("No trace data to generate coverage from"));
         } else {
+            // TODO(#3395): Use Ui spinner
             let _spinner = Spinner::create_with_message("Running cairo-coverage");
             run_coverage(
                 saved_trace_data_paths,

crates/forge-runner/src/lib.rs

@@ -0,0 +1,10 @@
+[package]
+name = "foundry-ui"
+version.workspace = true
+edition.workspace = true
+
+[dependencies]
+serde.workspace = true
+serde_json.workspace = true
+anyhow.workspace = true
+starknet-types-core.workspace = true

crates/foundry-ui/Cargo.toml

@@ -0,0 +1,53 @@
+pub use message::*;
+
+pub mod message;
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
+pub enum OutputFormat {
+    #[default]
+    Human,
+    Json,
+}
+
+/// An abstraction around console output which stores preferences for output format (human vs JSON),
+/// colour, etc.
+///
+/// All messaging (basically all writes to `stdout`) must go through this object.
+#[derive(Debug, Default)]
+pub struct UI {
+    output_format: OutputFormat,
+    // TODO(#3395): Add state here, that can be used for spinner
+}
+
+impl UI {
+    /// Create a new [`UI`] instance configured with the given output format.
+    #[must_use]
+    pub fn new(output_format: OutputFormat) -> Self {
+        Self { output_format }
+    }
+
+    // TODO: Will be removed in 3022-3-use-foundry-ui-in-sncast
+    /// Get the output format of this [`UI`] instance.
+    #[must_use]
+    pub fn output_format(&self) -> OutputFormat {
+        self.output_format
+    }
+
+    /// Create a [`String`] representation of the given message based on the configured output format.
+    fn format_message(&self, message: &impl Message) -> String {
+        match self.output_format {
+            OutputFormat::Human => message.text(),
+            OutputFormat::Json => message.json().to_string(),
+        }
+    }
+
+    /// Print the given message to stdout using the configured output format.
+    pub fn println(&self, message: &impl Message) {
+        println!("{}", self.format_message(message));
+    }
+
+    /// Print the given message to stderr using the configured output format.
+    pub fn eprintln(&self, message: &impl Message) {
+        eprintln!("{}", self.format_message(message));
+    }
+}

crates/foundry-ui/src/lib.rs

@@ -0,0 +1,24 @@
+use serde::Serialize;
+use serde_json::{Value, json};
+
+/// A typed object that can be either printed as a human-readable message or serialized as JSON.
+pub trait Message: Serialize {
+    /// Return textual (human) representation of this message.
+    fn text(&self) -> String;
+
+    /// Return JSON representation of this message.
+    fn json(&self) -> Value;
+}
+
+impl<T: ToString> Message for T
+where
+    T: Serialize,
+{
+    fn text(&self) -> String {
+        self.to_string()
+    }
+
+    fn json(&self) -> Value {
+        json!({ "message": self.to_string() })
+    }
+}

crates/foundry-ui/src/message.rs

@@ -55,6 +55,7 @@ dirs.workspace = true
 dialoguer.workspace = true
 toml_edit.workspace = true
 num-traits.workspace = true
+foundry-ui = { path = "../foundry-ui" }
 
 [dev-dependencies]
 ctor.workspace = true

crates/foundry-ui/src/output.rs

@@ -132,7 +132,7 @@ mod tests {
     use crate::{
         Network,
         helpers::block_explorer::Service,
-        response::{explorer_link::OutputLink, structs::DeployResponse},
+        response::{deploy::DeployResponse, explorer_link::OutputLink},
     };
     use conversions::padded_felt::PaddedFelt;
     use regex::Regex;

crates/sncast/Cargo.toml

@@ -6,5 +6,6 @@ pub mod configuration;
 pub mod constants;
 pub mod fee;
 pub mod interactive;
+pub mod output_format;
 pub mod rpc;
 pub mod scarb_utils;