Docs: Update README.md and add `boa_cli`'s README.md (#3659)

* Build out boa_cli readme

* Review feedback

README.md

@@ -32,15 +32,16 @@ Prefer a CLI? Feel free to try out `boa_cli`!
 
 Boa currently publishes and actively maintains the following crates:
 
-- **`boa_ast`** - Boa's ECMAScript Abstract Syntax Tree.
+- **`boa_ast`** - Boa's ECMAScript Abstract Syntax Tree
+- **`boa_cli`** - Boa's CLI && REPL implementation
 - **`boa_engine`** - Boa's implementation of ECMAScript builtin objects and
-  execution.
-- **`boa_gc`** - Boa's garbage collector.
-- **`boa_interner`** - Boa's string interner.
-- **`boa_parser`** - Boa's lexer and parser.
-- **`boa_profiler`** - Boa's code profiler.
-- **`boa_icu_provider`** - Boa's ICU4X data provider.
-- **`boa_runtime`** - Boa's WebAPI features.
+  execution
+- **`boa_gc`** - Boa's garbage collector
+- **`boa_interner`** - Boa's string interner
+- **`boa_parser`** - Boa's lexer and parser
+- **`boa_profiler`** - Boa's code profiler
+- **`boa_icu_provider`** - Boa's ICU4X data provider
+- **`boa_runtime`** - Boa's WebAPI features
 
 Please note: the `Boa` and `boa_unicode` crate are deprecated.
 
@@ -58,8 +59,9 @@ boa_engine = "0.17.3"
 Then in `main.rs`, copy the below:
 
 ```rust
-use boa_engine::{Context, Source};
+use boa_engine::{Context, Source, JsResult};
 
+fn main() -> JsResult<()> {
   let js_code = r#"
       let two = 1 + 1;
       let definitely_not_four = two + "2";
@@ -71,18 +73,13 @@ let js_code = r#"
   let mut context = Context::default();
 
   // Parse the source code
-match context.eval(Source::from_bytes(js_code)) {
-    Ok(res) => {
-        println!(
-            "{}",
-            res.to_string(&mut context).unwrap().to_std_string_escaped()
-        );
-    }
-    Err(e) => {
-        // Pretty print the error
-        eprintln!("Uncaught {e}");
+  let result = context.eval(Source::from_bytes(js_code))?;
+
+  println!("{}", result.display());
+
+  Ok(())
 }
-};
+
 ```
 
 Now, all that's left to do is `cargo run`.
@@ -94,6 +91,7 @@ Congrats! You've executed your first `JavaScript` using `Boa`!
 For more information on `Boa`'s API. Feel free to check out our documentation.
 
 [**Release Documentation**](https://docs.rs/boa_engine/latest/boa_engine/)
+
 [**Dev `main` Documentation**](https://boajs.dev/boa/doc/boa_engine/index.html)
 
 ## Conformance

cli/README.md

@@ -0,0 +1,71 @@
+# Boa CLI
+
+Boa CLI is `Boa`'s REPL implementation to execute `JavaScript` directly from
+your CLI.
+
+## Installation
+
+`boa_cli` can be installed directly via `Cargo`.
+
+```shell
+    cargo install boa_cli
+```
+
+<!-- TODO (nekevss): Add a non cargo-based installation options / build out further -->
+
+## Usage
+
+<!-- TODO (nekevss): Potentially add CI driven gifs with https://github.com/charmbracelet/vhs -->
+<!-- NOTE (nekevss): VHS is currently bugged and non-functional on Windows. -->
+
+Once installed, your good to go!
+
+To execute some JavaScript source code, navigate to the directy of your choosing and type:
+
+```shell
+    boa test.js
+```
+
+Or if you'd like to use Boa's REPL, simply type:
+
+```shell
+    boa
+```
+
+## CLI Options
+
+```txt
+Usage: boa [OPTIONS] [FILE]...
+
+Arguments:
+  [FILE]...  The JavaScript file(s) to be evaluated
+
+Options:
+      --strict                        Run in strict mode
+  -a, --dump-ast [<FORMAT>]           Dump the AST to stdout with the given format [possible values: debug, json, json-pretty]
+  -t, --trace                         Dump the AST to stdout with the given format
+      --vi                            Use vi mode in the REPL
+  -O, --optimize
+      --optimizer-statistics
+      --flowgraph [<FORMAT>]          Generate instruction flowgraph. Default is Graphviz [possible values: graphviz, mermaid]
+      --flowgraph-direction <FORMAT>  Specifies the direction of the flowgraph. Default is top-top-bottom [possible values: top-to-bottom, bottom-to-top, left-to-right, right-to-left]
+      --debug-object                  Inject debugging object `$boa`
+  -m, --module                        Treats the input files as modules
+  -r, --root <ROOT>                   Root path from where the module resolver will try to load the modules [default: .]
+  -h, --help                          Print help (see more with '--help')
+  -V, --version                       Print version
+```
+
+## Features
+
+Boa's CLI currently has a variety of features (as listed in `Options`).
+
+Features include:
+
+- Implemented runtime features (please note that only `Console` is currently implemented)
+- AST Visibility: View the compiled Boa AST (--dump-ast)
+- Tracing: Enabling a vm tracing when executing any JavaScript
+- Flowgraphs: View a generated (with various provided options)
+- Debugging: Boa's CLI comes with an implemented `$boa` debug object with various functionality (see documentation).
+
+Have an idea for a feature? Feel free to submit an issue and/or contribute!

cli/src/main.rs

@@ -1,4 +1,4 @@
-//! A ECMAScript REPL implementation based on boa_engine.
+//! A CLI implementation for `boa_engine` that comes complete with file execution and a REPL.
 #![doc = include_str!("../ABOUT.md")]
 #![doc(
     html_logo_url = "https://raw.githubusercontent.com/boa-dev/boa/main/assets/logo.svg",