feat: Added the ability to use the TEACH-ME mode

README.md

@@ -71,6 +71,15 @@ cargo near
 
 Starts interactive mode that will allow to explore all the available commands.
 
+---
+Use `--teach-me` flag if you want to know "how it works".
+
+```console
+cargo near --teach-me
+```
+
+Starts an interactive mode with an explanation of the execution of the selected command.
+
 ---
 Additionally depends on [Git](https://git-scm.com/) binary being installed, besides [cargo](https://github.com/rust-lang/cargo).
 

cargo-near-build/Cargo.toml

@@ -34,6 +34,7 @@ tempfile = { version = "3.10.1", optional = true }
 shell-words = { version = "1.0.0", optional = true }
 wasm-opt = "=0.116.1"
 humantime = "2.1.0"
+indenter = "0.3"
 
 [target.'cfg(target_os = "linux")'.dependencies]
 nix = { version = "0.29.0", features = ["user", "process"], optional = true }

cargo-near-build/src/cargo_native/compile.rs

@@ -5,6 +5,7 @@ use cargo_metadata::{Artifact, Message};
 use eyre::{ContextCompat, WrapErr};
 use std::io::BufRead;
 
+use crate::pretty_print;
 use crate::types::near::build::input::ColorPreference;
 use crate::types::{cargo::manifest_path::ManifestPath, near::build::output::CompilationArtifact};
 
@@ -121,7 +122,11 @@ where
 
     if let Some(path) = working_dir {
         let path = crate::fs::force_canonicalize_dir(path.as_ref())?;
-        tracing::debug!("Setting cargo working dir to '{}'", path);
+        tracing::info!(
+            target: "near_teach_me",
+            parent: &tracing::Span::none(),
+            "Setting cargo working dir to '{}'", path
+        );
         cmd.current_dir(path);
     }
 
@@ -134,7 +139,12 @@ where
         ColorPreference::Never => cmd.args(["--color", "never"]),
     };
 
-    tracing::info!("Invoking cargo: {:#?}", cmd);
+    tracing::info!(
+        target: "near_teach_me",
+        parent: &tracing::Span::none(),
+        "Invoking cargo:\n{}",
+        pretty_print::indent_payload(&format!("{:#?}", cmd))
+    );
 
     let mut child = cmd
         // capture the stdout to return from this function as bytes

cargo-near-build/src/cargo_native/target.rs

@@ -2,6 +2,8 @@ use std::{ffi::OsStr, io::BufRead, path::PathBuf, process::Command};
 
 use eyre::WrapErr;
 
+use crate::pretty_print;
+
 pub const COMPILATION_TARGET: &str = "wasm32-unknown-unknown";
 
 pub fn wasm32_exists() -> bool {
@@ -11,12 +13,16 @@ pub fn wasm32_exists() -> bool {
         Ok(wasm32_target_libdir_path) => {
             if wasm32_target_libdir_path.exists() {
                 tracing::info!(
+                    target: "near_teach_me",
+                    parent: &tracing::Span::none(),
                     "Found {COMPILATION_TARGET} in {:?}",
                     wasm32_target_libdir_path
                 );
                 true
             } else {
                 tracing::info!(
+                    target: "near_teach_me",
+                    parent: &tracing::Span::none(),
                     "Failed to find {COMPILATION_TARGET} in {:?}",
                     wasm32_target_libdir_path
                 );
@@ -38,16 +44,24 @@ pub fn wasm32_exists() -> bool {
 }
 
 fn get_rustc_wasm32_unknown_unknown_target_libdir() -> eyre::Result<PathBuf> {
-    let command = Command::new("rustc")
-        .args(["--target", COMPILATION_TARGET, "--print", "target-libdir"])
-        .output()?;
+    let mut command = Command::new("rustc");
+    command.args(["--target", COMPILATION_TARGET, "--print", "target-libdir"]);
+
+    tracing::info!(
+        target: "near_teach_me",
+        parent: &tracing::Span::none(),
+        "Execution command:\n{}",
+        pretty_print::indent_payload(&format!("`{:?}`", command).replace("\"", ""))
+    );
 
-    if command.status.success() {
-        Ok(String::from_utf8(command.stdout)?.trim().into())
+    let output = command.output()?;
+
+    if output.status.success() {
+        Ok(String::from_utf8(output.stdout)?.trim().into())
     } else {
         eyre::bail!(
             "Getting rustc's wasm32-unknown-unknown target wasn't successful. Got {}",
-            command.status,
+            output.status,
         )
     }
 }
@@ -62,7 +76,12 @@ where
     let mut cmd = Command::new(rustup);
     cmd.args(args);
 
-    tracing::info!("Invoking rustup: {:?}", cmd);
+    tracing::info!(
+        target: "near_teach_me",
+        parent: &tracing::Span::none(),
+        "Invoking rustup:\n{}",
+        pretty_print::indent_payload(&format!("`{}`", format!("{:?}", cmd).replace("\"", "")))
+    );
 
     let child = cmd
         .stdout(std::process::Stdio::piped())

cargo-near-build/src/env_keys.rs

@@ -11,6 +11,8 @@ pub(crate) const CARGO_NEAR_ABI_SCHEMA_VERSION: &str = "CARGO_NEAR_ABI_SCHEMA_VE
 /// module contains variables, which are set to configure build with WASM reproducibility,
 /// which correspond to some fields of `ContractSourceMetadata` in <https://github.com/near/NEPs/blob/master/neps/nep-0330.md>
 pub mod nep330 {
+    use crate::pretty_print;
+    use std::collections::HashMap;
 
     // ====================== NEP-330 1.2.0 - Build Details Extension ===========
     /// NEP-330 1.2.0
@@ -35,12 +37,21 @@ pub mod nep330 {
     }
 
     pub(crate) fn print_env() {
-        tracing::info!("Variables, relevant for reproducible builds:");
+        let mut env_map: HashMap<&str, String> = HashMap::new();
         for key in [BUILD_ENVIRONMENT, CONTRACT_PATH, SOURCE_CODE_SNAPSHOT] {
             let value = std::env::var(key)
                 .map(|val| format!("'{}'", val))
                 .unwrap_or("unset".to_string());
-            tracing::info!("{}={}", key, value);
+            env_map.insert(
+                key,
+                value.replace("'", "").replace("\"", "").replace(",", " "),
+            );
         }
+        tracing::info!(
+            target: "near_teach_me",
+            parent: &tracing::Span::none(),
+            "Variables, relevant for reproducible builds:\n{}",
+            pretty_print::indent_payload(&format!("{:#?}", env_map))
+        );
     }
 }

cargo-near-build/src/near/abi/generate/dylib.rs

@@ -4,6 +4,7 @@ use std::fs;
 use camino::Utf8Path;
 
 use crate::cargo_native::Dylib;
+use crate::pretty_print;
 use crate::types::near::build::output::CompilationArtifact;
 
 pub fn extract_abi_entries(
@@ -12,7 +13,9 @@ pub fn extract_abi_entries(
     let dylib_path: &Utf8Path = &artifact.path;
     let dylib_file_contents = fs::read(dylib_path)?;
     let object = symbolic_debuginfo::Object::parse(&dylib_file_contents)?;
-    tracing::debug!(
+    tracing::info!(
+        target: "near_teach_me",
+        parent: &tracing::Span::none(),
         "A dylib was built at {:?} with format {} for architecture {}",
         &dylib_path,
         &object.file_format(),
@@ -26,7 +29,12 @@ pub fn extract_abi_entries(
     if near_abi_symbols.is_empty() {
         eyre::bail!("No NEAR ABI symbols found in the dylib");
     }
-    tracing::debug!("Detected NEAR ABI symbols: {:?}", &near_abi_symbols);
+    tracing::info!(
+        target: "near_teach_me",
+        parent: &tracing::Span::none(),
+        "Detected NEAR ABI symbols:\n{}",
+        pretty_print::indent_payload(&format!("{:#?}", &near_abi_symbols))
+    );
 
     let mut entries = vec![];
     unsafe {

cargo-near-build/src/near/docker_build/subprocess_step.rs

@@ -11,6 +11,7 @@ use std::{
 use nix::unistd::{getgid, getuid};
 
 use crate::env_keys;
+use crate::pretty_print;
 use crate::types::near::docker_build::subprocess::{container_paths, env_vars};
 use crate::types::near::docker_build::{cloned_repo, metadata};
 
@@ -71,7 +72,12 @@ pub fn run(
                 &container_paths.crate_path,
             ];
             let stdin_is_terminal = std::io::stdin().is_terminal();
-            tracing::debug!("input device is a tty: {}", stdin_is_terminal);
+            tracing::info!(
+                target: "near_teach_me",
+                parent: &tracing::Span::none(),
+                "Input device is a TTY:\n{}",
+                pretty_print::indent_payload(&stdin_is_terminal.to_string())
+            );
             if stdin_is_terminal
                 && std::env::var(env_keys::nep330::nonspec::SERVER_DISABLE_INTERACTIVE).is_err()
             {
@@ -83,7 +89,12 @@ pub fn run(
             docker_args.extend(vec![&docker_image, "/bin/bash", "-c"]);
 
             docker_args.push(&shell_escaped_cargo_cmd);
-            tracing::debug!("docker command : {:#?}", docker_args);
+            tracing::info!(
+                target: "near_teach_me",
+                parent: &tracing::Span::none(),
+                "Docker command:\n{}",
+                pretty_print::indent_payload(&format!("{:#?}", docker_args))
+            );
             docker_args
         };
 

cargo-near-build/src/pretty_print.rs

@@ -33,3 +33,14 @@ pub fn duration(start: Instant, activity: &str) {
         humantime::format_duration(duration)
     );
 }
+
+pub fn indent_payload(s: &str) -> String {
+    use std::fmt::Write;
+
+    let mut indented_string = String::new();
+    indenter::indented(&mut indented_string)
+        .with_str(" |    ")
+        .write_str(s)
+        .ok();
+    indented_string
+}

cargo-near-build/src/types/cargo/metadata.rs

@@ -5,6 +5,7 @@ use cargo_metadata::{MetadataCommand, Package};
 use colored::Colorize;
 use eyre::{ContextCompat, OptionExt, WrapErr};
 
+use crate::pretty_print;
 use crate::types::near::build::buildtime_env;
 
 use super::manifest_path::ManifestPath;
@@ -67,7 +68,11 @@ impl CrateMetadata {
         } else {
             self.target_directory.clone()
         };
-        tracing::debug!("resolved output directory: {}", result);
+        tracing::info!(
+            target: "near_teach_me",
+            parent: &tracing::Span::none(),
+            "Resolved output directory: {}", result
+        );
         Ok(result)
     }
 
@@ -136,7 +141,11 @@ fn get_cargo_metadata(
     no_locked: bool,
     cargo_target_dir: Option<&buildtime_env::CargoTargetDir>,
 ) -> eyre::Result<(cargo_metadata::Metadata, Package)> {
-    tracing::info!("Fetching cargo metadata for {}", manifest_path.path);
+    tracing::info!(
+        target: "near_teach_me",
+        parent: &tracing::Span::none(),
+        "Fetching cargo metadata for {}", manifest_path.path
+    );
     let mut cmd = MetadataCommand::new();
     if !no_locked {
         cmd.other_options(["--locked".to_string()]);
@@ -147,6 +156,12 @@ fn get_cargo_metadata(
     }
     let cmd = cmd.manifest_path(&manifest_path.path);
     tracing::debug!("metadata command: {:#?}", cmd.cargo_command());
+    tracing::info!(
+        target: "near_teach_me",
+        parent: &tracing::Span::none(),
+        "Execution command:\n{}",
+        pretty_print::indent_payload(&format!("`{:?}`", cmd.cargo_command()).replace("\"", ""))
+    );
     let metadata = cmd.exec();
     if let Err(cargo_metadata::Error::CargoMetadata { stderr }) = metadata.as_ref() {
         if stderr.contains("remove the --locked flag") {

cargo-near/src/commands/build_command/mod.rs

@@ -116,7 +116,12 @@ fn get_env_key_vals(input: Vec<String>) -> Vec<(String, String)> {
     let dedup_map: HashMap<String, String> = HashMap::from_iter(iterator);
 
     let result = dedup_map.into_iter().collect();
-    tracing::trace!("passed additional environment pairs: {:#?}", result);
+    tracing::info!(
+        target: "near_teach_me",
+        parent: &tracing::Span::none(),
+        "Passed additional environment pairs:\n{}",
+        near_cli_rs::common::indent_payload(&format!("{:#?}", result))
+    );
     result
 }