feat: add triton-tui, a TUI for debugging programs in Triton assembly

Cargo.toml

@@ -1,5 +1,5 @@
 [workspace]
-members = ["triton-vm", "constraint-evaluation-generator"]
+members = ["triton-vm", "triton-tui", "constraint-evaluation-generator"]
 resolver = "2"
 
 [profile.test]

triton-tui/.config/default_config.json

@@ -0,0 +1,43 @@
+{
+    "keybindings": {
+        "Home": {
+            "<q>": "Quit",
+            "<Ctrl-c>": "Quit",
+            "<Ctrl-z>": "Suspend",
+
+            "<h>": "Mode::Help",
+            "<m>": "Mode::Memory",
+
+            "<c>": "Continue",
+            "<s>": "Step",
+            "<n>": "Next",
+            "<f>": "Finish",
+            "<u>": "Undo",
+            "<r>": "Reset",
+
+            "<t><a>": "ToggleAll",
+            "<t><t>": "ToggleTypeHintDisplay",
+            "<t><c>": "ToggleCallStackDisplay",
+            "<t><s>": "ToggleSpongeStateDisplay",
+            "<t><i>": "ToggleInputDisplay"
+        },
+        "Help": {
+            "<q>": "Quit",
+            "<Ctrl-c>": "Quit",
+            "<Ctrl-z>": "Suspend",
+
+            "<h>": "HideHelpScreen",
+            "<m>": "Mode::Memory",
+            "<esc>": "Mode::Home"
+        },
+        "Memory": {
+            "<q>": "Quit",
+            "<Ctrl-c>": "Quit",
+            "<Ctrl-z>": "Suspend",
+
+            "<h>": "Mode::Help",
+            "<m>": "Mode::Home",
+            "<esc>": "Mode::Home"
+        }
+    }
+}

triton-tui/.envrc

@@ -0,0 +1,3 @@
+export TRITON_TUI_CONFIG=$(pwd)/.config
+export TRITON_TUI_DATA=$(pwd)/.data
+export TRITON_TUI_LOG_LEVEL=debug

triton-tui/Cargo.toml

@@ -0,0 +1,57 @@
+[package]
+name = "triton-tui"
+description = "A TUI that helps debugging programs written for Triton VM."
+
+version.workspace = true
+edition.workspace = true
+authors.workspace = true
+license.workspace = true
+homepage.workspace = true
+documentation.workspace = true
+repository.workspace = true
+
+[dependencies]
+arbitrary.workspace = true
+better-panic = "0.3"
+clap = { version = "4", features = ["derive", "cargo", "wrap_help", "unicode", "string", "unstable-styles"] }
+color-eyre = "0.6"
+config = "0.13"
+crossterm = { version = "0.27", features = ["serde", "event-stream"] }
+derive_deref = "1"
+directories = "5"
+fs-err = "2.0"
+futures = "0.3"
+human-panic = "1"
+itertools.workspace = true
+lazy_static.workspace = true
+libc = "0.2"
+num-traits.workspace = true
+ratatui = { version = "0.25", features = ["serde", "macros"] }
+serde.workspace = true
+serde_json = "1.0"
+signal-hook = "0.3"
+strip-ansi-escapes = "0.2"
+strum.workspace = true
+tokio = { version = "1", features = ["full"] }
+tokio-util = "0.7"
+tracing = "0.1"
+tracing-error = "0.2"
+tracing-subscriber = { version = "0.3", features = ["env-filter", "serde"] }
+triton-vm = { path = "../triton-vm" }
+tui-textarea = "0.4"
+
+[dev-dependencies]
+assert2.workspace = true
+pretty_assertions.workspace = true
+proptest.workspace = true
+proptest-arbitrary-interop.workspace = true
+rexpect = "0.5"
+test-strategy.workspace = true
+
+[[bin]]
+name = "triton-tui"
+path = "src/main.rs"
+
+[[test]]
+name = "integration"
+path = "tests/tests.rs"

triton-tui/README.md

@@ -0,0 +1,29 @@
+# Triton TUI
+
+A TUI to run and debug programs written for Triton VM.
+
+<img alt="Example run of Triton TUI" src="./examples/triton-tui.gif" width="800" />
+
+## Getting Started
+
+Triton TUI tries to be helpful 🙂. List possible (and required) arguments with `triton-tui --help`. In the TUI, press `h` to access the help screen.
+
+The [example program](./examples/program.tasm), serving as the tutorial, can be run with
+
+```sh
+triton-tui --program examples/program.tasm
+```
+
+## Installation
+
+Through [crates.io](https://crates.io/crates/triton-tui):
+
+```sh
+cargo install triton-tui
+```
+
+Locally:
+
+```sh
+cargo install --path .
+```

triton-tui/build.rs

@@ -0,0 +1,62 @@
+fn main() {
+    let git_dir = maybe_get_git_dir();
+    trigger_rebuild_if_head_or_some_relevant_ref_changes(git_dir);
+
+    let git_output = std::process::Command::new("git")
+        .args(["describe", "--always", "--tags", "--long", "--dirty"])
+        .output()
+        .ok();
+    let git_info = git_output
+        .as_ref()
+        .and_then(|output| std::str::from_utf8(&output.stdout).ok().map(str::trim));
+    let cargo_pkg_version = env!("CARGO_PKG_VERSION");
+
+    // Default git_describe to cargo_pkg_version
+    let mut git_describe = String::from(cargo_pkg_version);
+
+    if let Some(git_info) = git_info {
+        // If the `git_info` contains `CARGO_PKG_VERSION`, we simply use `git_info` as it is.
+        // Otherwise, prepend `CARGO_PKG_VERSION` to `git_info`.
+        if git_info.contains(cargo_pkg_version) {
+            // Remove the 'g' before the commit sha
+            let git_info = &git_info.replace('g', "");
+            git_describe = git_info.to_string();
+        } else {
+            git_describe = format!("v{cargo_pkg_version}-{git_info}");
+        }
+    }
+
+    println!("cargo:rustc-env=TRITON_TUI_GIT_INFO={git_describe}");
+}
+
+fn maybe_get_git_dir() -> Option<String> {
+    let git_output = std::process::Command::new("git")
+        .args(["rev-parse", "--git-dir"])
+        .output()
+        .ok();
+    git_output.as_ref().and_then(|output| {
+        std::str::from_utf8(&output.stdout)
+            .ok()
+            .and_then(|s| s.strip_suffix('\n').or_else(|| s.strip_suffix("\r\n")))
+            .map(str::to_string)
+    })
+}
+
+fn trigger_rebuild_if_head_or_some_relevant_ref_changes(git_dir: Option<String>) {
+    if let Some(git_dir) = git_dir {
+        let git_path = std::path::Path::new(&git_dir);
+        let refs_path = git_path.join("refs");
+        if git_path.join("HEAD").exists() {
+            println!("cargo:rerun-if-changed={git_dir}/HEAD");
+        }
+        if git_path.join("packed-refs").exists() {
+            println!("cargo:rerun-if-changed={git_dir}/packed-refs");
+        }
+        if refs_path.join("heads").exists() {
+            println!("cargo:rerun-if-changed={git_dir}/refs/heads");
+        }
+        if refs_path.join("tags").exists() {
+            println!("cargo:rerun-if-changed={git_dir}/refs/tags");
+        }
+    }
+}

triton-tui/examples/non_determinism.json

@@ -0,0 +1,5 @@
+{
+    "individual_tokens" : [497, 598, 699],
+    "digests" : [[3, 4, 5, 6, 7], [4, 5, 6, 7, 8]],
+    "ram" : {"5": 50, "6": 60, "7": 70}
+}

triton-tui/examples/program.tasm

@@ -0,0 +1,52 @@
+//! Demonstrates use and functionality of the Triton VM TUI.
+//!
+//! Serves as the tutorial: execution intentionally fails at first, hopefully
+//! encouraging you to play around. :) The inline comments should make matters trivial.
+//!
+//! Press `h` in Triton VM TUI to show the help screen.
+
+// Let's start!
+push 3
+hint loop_counter = stack[0]        // Current stack can be annotated to help debugging.
+break
+
+call my_loop
+hint numbers: array = stack[1..4]   // Annotations also work with ranges.
+
+call check_result
+call write_to_memory
+call read_from_secret_input
+call sponge_instructions
+halt
+
+my_loop:
+    dup 0 push 0 eq skiz return
+    read_io 3                       // call with `--input ./public_input.txt`
+    mul mul
+    break
+    dup 0 write_io 1
+    swap 1 push -1 add recurse
+
+check_result:                       // Try enabling
+    // pop 1                        // <- this line for
+    assert                          // <- this assertion to work.
+    return                          // Hot reload & reset of the VM is `r`.
+
+write_to_memory:
+    push 42
+    write_mem 2                     // You can inspect memory with `m`.
+    pop 1
+    return
+
+read_from_secret_input:
+    divine 3                        // flag `--non-determinism ./non_determinism.json`
+    mul mul
+    swap 5
+    divine_sibling pop 5
+    divine_sibling hash
+    return
+
+sponge_instructions:
+    sponge_init                     // Show the Sponge state with `t,s`.
+    sponge_squeeze
+    return

triton-tui/examples/public_input.txt

@@ -0,0 +1,3 @@
+ 2  3  5
+17 19 42
+ 1  1  1

triton-tui/examples/triton-tui.tape

@@ -0,0 +1,36 @@
+Output triton-tui.gif
+
+Set Shell zsh
+Set Width 2000
+Set Height 1000
+
+Sleep 1s
+Hide
+Type "triton-tui -p ./program.tasm -i public_input.txt -n non_determinism.json"
+Show
+Sleep 1s
+Enter
+Sleep 3s
+
+Type "c"
+Sleep 2s
+Type "c"
+Sleep 2s
+Type "c"
+Sleep 2s
+Type "ti"
+Type "tc"
+Sleep 2s
+Type "ff"
+Sleep 3s
+
+Type "m"
+Sleep 3s
+Enter
+Type "30"
+Enter
+Sleep 3s
+
+Hide
+Type "q"
+Ctrl+D