Build a Rust CLI to create notes for your digital garden. Step by step you will build, run, and test the CLI while learning core Rust concepts like move/copy semantics.

Chris Biscardi

Create a Digital Garden CLI with Rust

This course walks you through Rustlings exercises in a way that explains what's going on in each exercise. We cover everything from basic types to generics and threading.

Learning Rust by Working Through the Rustlings Exercises

You will come away from this collection with the ability to ship an API that you can use on any of your sites.

Building an OpenGraph image generation API with Cloudinary, Netlify Functions, and React

This collection includes introductory level material for AWS DynamoDB. We cover what DynamoDB is, when you'd use it, and the vocabulary you'll need to understand documentation and talks in the ecosystem.

You'll come out of this playlist with the ability to understand what people mean when they say DynamoDB and the base you need to get started yourself.

**View and contribute to the [Community Notes!](https://github.com/eggheadio-projects/intro-to-dynamodb)**

Intro to DynamoDB

This collection is a sequel to the [Building a Serverless JAMStack Todo app with Netlify, Gatsby, GraphQL, and FaunaDB](https://egghead.io/playlists/building-a-serverless-jamstack-todo-app-with-netlify-gatsby-graphql-and-faunadb-53bb) collection. In this collection we take the TODO application we built and convert it to run using Netlify Identity, AWS Lambda (using the serverless framework) and DynamoDB. We cover

* Fauna vs DynamoDB and when to use each
* Setting up AWS accounts
* Creating DynamoDB tables and data modeling differences between Fauna and Dynamo
* Converting our Netlify Functions deployment to a Serverless Framework deployment
* Implementing Custom authorizer functions on AWS

It uses tools that remove as many of the barriers as possible. Netlify Functions grows into Serverless Framework adn AWS Lambda, Netlify Identity is kept around, and FaunaDB can grows into DynamoDB.



Converting a Serverless App to run on AWS Lambda and DynamoDB with Serverless Framework

This playlist covers all of the ways to use the node.js DocumentClient to interact with one or more DynamoDB tables.


note: We do not cover scan() as it is not recommended for most usage and if you need it you'll know how to read the documentation to use it by the end of this collection.

DynamoDB: The Node.js DocumentClient

Database

When you see the word “theme” you might think of the visual aspects of a site or code editor where setting an option in one place can change the look everywhere.

Gatsby Themes take this idea to another level by allowing you to change and compose entire pieces of functionality.

In this advanced course, you will iteratively convert a fictitious SaaS website with marketing, eCommerce, blog, and dashboard pages into a set of horizontally composed Gatsby Themes.

After everything's been split up, you will build a deeper understanding of parent/child theme relationships by exploring the blog data model with schema customization APIs that allow us to create multiple child themes with data sourced from different node types.

Composable Gatsby Themes

MDX is an authorable format that lets you seamlessly write JSX in your Markdown documents. 

Gatsby is a free and open source framework based on React that helps developers build blazing fast websites and apps

Together, they combine to create a powerful platform for docs, blogs, and other rich applications.

Building Websites with MDX and Gatsby

This application serves as an introduction to building products with a JAMStack and Serverless approach. We cover everything from the beginning:

* starting with the Gatsby client
* handling authentication with Netlify Identity
* Shipping a GraphQL server on Netlify Functions
* Building in access control with a serverless capable database

It uses tools that remove as many of the barriers as possible while also allowing upgrading in the future. Netlify Functions can grow into AWS Lambda, Netlify Identity can grow into Auth0 or Cognito, and FaunaDB can grow into DynamoDB.

Building a Serverless JAMStack Todo app with Netlify, Gatsby, GraphQL, and FaunaDB

Jamstack

Chris Biscardi Landing Page

 Courses from Chris Biscardi

In this course, Chris takes a README-driven approach to build out a Rust CLI that supports content authoring for a digital garden.

Specifically, you'll work through the first command for the CLI, writing files. You start by initializing a new Cargo binary crate through creating the `write` command that allows you to create files (and their contents) to the folder that you set. 

Step by step you'll learn about:
- Handling user input
- Error handling
- Rust Move semantics
- Rust Copy semantics
- Integration testing

...and more!

Rust is a systems programming language that runs blazingly fast, prevents segfaults, and guarantees thread safety.

rust

Creating a Digital Garden CLI with Rust

While we have `test_write_with_title`
which tests the garden CLI with a given
title flag, we can also set up additional
tests, such as for using a written title
in the document for the filename.

Copy/pasting the code from test one into
test two is a lot of duplication, and
setting up the fake editor isn't going
to change across tests, so let's abstract
the creation of the temporary directory,
the fake editor script path, and the
`Command` itself into a utility function.

The port is relatively straightforward,
with the only changes being that we cut
off the `cmd` modifications before the
`.arg` calls, and now have to return
the `cmd` and the `temp_dir` in a tuple.

We return the actual `Command` and `TempDir`,
yielding ownership to the calling function
because we have no further use for them here,
but the calling function will need to mutate
the `Command` more, and use `TempDir` to test.

```rust
fn setup_command() -> (Command, assert_fs::TempDir) {
    let temp_dir = assert_fs::TempDir::new().unwrap();

    let mut cmd = Command::cargo_bin("garden").unwrap();
    let fake_editor_path = std::env::current_dir()
        .expect("expect to be in a dir")
        .join("tests")
        .join("fake-editor.sh");
    if !fake_editor_path.exists() {
        panic!(
            "fake editor shell script could not be found"
        )
    }

    cmd.env("EDITOR", fake_editor_path.into_os_string())
        .env("GARDEN_PATH", temp_dir.path());
    (cmd, temp_dir)
}
```

The new write tests are considerably shorter
now and focus mostly on which subcommand to
call, and what the user interaction with that
subcommand is.

```rust

fn test_write_with_title() {
    let (mut cmd, temp_dir) = setup_command();
    let assert = cmd
        .arg("write")
        .arg("-t")
        .arg("atitle")
        .write_stdin("N\n".as_bytes())
        .assert();

    assert.success();

    temp_dir
        .child("atitle.md")
        .assert(predicate::path::exists());
}

fn test_write_with_written_title() {
    let (mut cmd, temp_dir) = setup_command();
    let assert = cmd
        .arg("write")
        .write_stdin("N\n".as_bytes())
        .assert();

    assert.success();

    temp_dir
        .child("testing.md")
        .assert(predicate::path::exists());
}
```

Abstracting test utilities inside integration test files

We can print lines to the terminal and
ask the user for various input. So let's
make the interface a bit more usable by
using colored output.

We can do this by bringing an extension
trait for formatting into scope:
`OwoColorize`.

Extension traits are one-off traits that
are used to add functions to a type that
our crate doesn't own. A crate can create
the new trait, then implement the
functions defined by that trait on a type
the crate doesn't own and if we bring that
trait into scope, the type will get the
extra functions. In this case, `OwoColorize`
is used for adding color functions to
formatters like Display and Debug.

We'll start with `ask_for_filename`

```rust
use color_eyre::owo_colors::OwoColorize;

fn ask_for_filename() -> Result<String> {
    rprompt::prompt_reply_stderr(&format!(
        "{}",
        "\
Enter filename
> "
        .blue()
        .bold(),
    ))
    .wrap_err("Failed to get filename")
    .map(|title| slug::slugify(title))
}
```

In `confirm_filename` we can use multiple
formatters to get different colors:

```rust
let result = rprompt::prompt_reply_stderr(&format!(
    "\
{} {}
Do you want a different title? (y/N): ",
    "current title:".green().bold(),
    raw_title,
))
.wrap_err("Failed to get input for y/n question")?;
```

Using owo_colors Extension Traits to colorize terminal output

`PathBuf` lets us check to see if a file
exists before writing to it, so we can
take advantage of that to make sure that
we don't overwrite a file that already
exists, even if the user has indicated
a title that would overwrite another file.

```
let mut i: usize = 0;
loop {
    let dest_filename = format!(
        "{}{}",
        filename,
        if i == 0 {
            "".to_string()
        } else {
            i.to_string()
        }
    );
    let mut dest = garden_path.join(dest_filename);
    dest.set_extension("md");
    if dest.exists() {
        i = i + 1;
    } else {
        fs::rename(garden_tmpfile, &dest)?;
        break;
    }
}
```

Checking for file existence with PathBuf to ensure unique filenames

We have been ignoring implementing tests for the write subcommand. Now is the time that we'll test the command we have been building.

We'll build out a fake editor script that our test will use to check if the command is functioning properly. We will then use `arg` to build the command as we would normally use it ourselves.

After writing the test, we'll see how to clean up after ourselves so that we aren't leaving testing artifacts leftover just from running a test.

---

How to integration test a cargo binary that calls
out to `EDITOR` for modifications and asks the
user for input.

First we'll create a fake editor script to use
instead of vim, etc.

`tests/fake_editor.sh` is a one-liner.

```shell
echo "testing" >> $1;
```

Then we'll write our test using `assert_cmd` to
build up a `Command` that points to the `garden`
binary in out `Cargo.toml`.

We grab the fake editor path script using
`std::env::current_dir()`, make sure the file
exists (which means we've grabbed the right
path), and spawn a new `Command` with the
`EDITOR` variable set to the fake editor
script. The equivalent call to our bin is

```shell
EDITOR=path/to/fake-editor.sh garden write -t atitle
```

And the rust code to execute.

```rust
fn test_write_with_title() {
    let mut cmd = Command::cargo_bin("garden").unwrap();
    let fake_editor_path = std::env::current_dir()
        .expect("expect to be in a dir")
        .join("tests")
        .join("fake-editor.sh");
    if !fake_editor_path.exists() {
        panic!(
            "fake editor shell script could not be found"
        )
    }

    let assert = cmd
        .env("EDITOR", fake_editor_path.into_os_string())
        .arg("write")
        .arg("-t")
        .arg("atitle")
        .write_stdin("N\n".as_bytes())
        .assert();

    assert.success();
}
```

Note that we're asserting that the command
exited sucessfully, and that we're inputing
`N\n` to the bin's stdin, which responds to
a request for user input after the editor
closes.

Note that this doesn't actually test for
the resulting file existence, and also that
we're writing our files out directly into
our default digital garden! We can solve
this with `assert_fs` and `predicates`.

We'll bring in both preludes (a prelude is
a bunch of stuff the library author thinks
will be useful to have around all the time)
and create a new temporary directory.

We'll use the `GARDEN_PATH` environment
variable to pass the temporary directory in
to the `garden` bin and that's it, we've
added a temporary directory to our test.
No more polluting the default garden!

```rust
use assert_fs::prelude::*;
use predicates::prelude::*;

fn test_write_with_title() {
    let temp_dir = assert_fs::TempDir::new().unwrap();

    let mut cmd = Command::cargo_bin("garden").unwrap();
    let fake_editor_path = std::env::current_dir()
        .expect("expect to be in a dir")
        .join("tests")
        .join("fake-editor.sh");
    if !fake_editor_path.exists() {
        panic!(
            "fake editor shell script could not be found"
        )
    }

    let assert = cmd
        .env("EDITOR", fake_editor_path.into_os_string())
        .env("GARDEN_PATH", temp_dir.path())
        .arg("write")
        .arg("-t")
        .arg("atitle")
        .write_stdin("N\n".as_bytes())
        .assert();

    assert.success();

    temp_dir
        .child("atitle.md")
        .assert(predicate::path::exists());
}
```

Now that's enough, but we can also check
to make sure the file we expect to exist
actually exists. `temp_dir.child` gives
us the possible file, and we can assert
on that file with a test from `predicates`
that tests to make sure the file exists.

```rust
temp_dir
    .child("atitle.md")
    .assert(predicate::path::exists());
```

Using assert_fs and predicates to integration test with a real temporary file system

What user experience do we want for the
act of writing?

We have a few options, including letting
users write directly in the console or giving
them a prepared file that they can then open
and write in.

Writing directly in the console doesn't give
a user access to their text editor of choice.
Which means lacking autocomplete, syntax
highlighting, snippets, and other functionality.

Creating a file and handling the path back to
the user doesn't quite work for us either, as
that reduces the utility of the garden write
command to the equivalent of running `touch
filename.md`.

So for our use case, we'd ideally like to open
the user's preferred editing environment,
whatever that happens to be, then wait for them
to be done with the file before continuing.

Since we're working with a CLI tool, we
can safely assume that our users either
know how to, or are willingly to learn how
to, set environment variables. This means we
can use the `EDITOR` variable to select an
editor to use. This is the same way `git commit`
works.

---

In Rust, there is a crate that handles not only
`EDITOR`, but also various fallbacks per-platform.
We'll take advantage of [edit](https://crates.io/crates/edit)
to call out to the user's choice of editor.

The quick usage of edit allows us to call the
`edit::edit` function, and get the user's data.

```rust
pub fn write(garden_path: PathBuf, title: Option<String>) -> Result<()> {
    dbg!(garden_path, title);
    let template = "# ";
    let content_from_user = edit::edit(template).wrap_err("unable to read writing")?;
    dbg!(content_from_user);
    todo!()
}
```

This results in a filename that looks like:
`.tmpBy0Yun` "somewhere else" on the filesystem,
in a location the user would never reasonably
find it. Ideally, if anything went wrong, the
user would be able to take a look at the
in-progress tempfile they were just working on,
which should be in an easily discoverable place
like the garden path.

*We don't want to lose a user's work.*

Additionally, the tempfile doesn't have a file
extension, which means that the user's editor
will be less likely to recognize it as a
markdown file, so we want to add `.md` to the
filepath.

```rust
use color_eyre::{eyre::WrapErr, Result};
use edit::{edit_file, Builder};
use std::io::{Read, Write};
use std::path::PathBuf;

const TEMPLATE: &[u8; 2] = b"# ";

pub fn write(garden_path: PathBuf, title: Option<String>) -> Result<()> {
    let (mut file, filepath) = Builder::new()
        .suffix(".md")
        .rand_bytes(5)
        .tempfile_in(&garden_path)
        .wrap_err("Failed to create wip file")?
        .keep()
        .wrap_err("Failed to keep tempfile")?;
    file.write_all(TEMPLATE)?;
    // let the user write whatever they want in their favorite editor
    // before returning to the cli and finishing up
    edit_file(filepath)?;
    // Read the user's changes back from the file into a string
    let mut contents = String::new();
    file.read_to_string(&mut contents)?;

    dbg!(contents);
    todo!()
}
```

We will use the `edit::Builder` API to generate
a random tempfile to let the user write content
into. The suffix is going to be `.md` and the
filename will be 5 random bytes. We also put
the tempfile in the garden path, which ensures
a user will be able to find it if necessary.

`wrap_err` (which requires the `eyre::WrapErr`
trait in scope) wraps the potential error
resulting from these calls with additional context,
making the original error the source, and we can
keep chaining after that. We `keep` the tempfile,
which would otherwise be deleted when all handles
closed, because if anything goes wrong after the
user inputs data, we want to make sure we don't
lose that data.

After the file is created, we write our template
out to the file before passing control to the
user. This requires the `std::io::Write` trait
in scope. We use a const for the file template
because it won't change. To make the `TEMPLATE`
a const, we also need to give it a type, which
is a two element byte array. Change the string
to see how the byte array length is checked at
compile time.

Since we have access to the `file` already, we
can read the contents back into a string after
the user is done editing. This requires having
the `std::io::Read` trait in scope.

And now we've let the user write into a file
which will stick around as long as we need it
to, and importantly will stick around if any
errors happen in the execution of the program,
so we lose no user data and can remove the
temporary file at the end of the program
ourselves if all goes well.

Passing control to the user's favorite editor (such as VSCode) from the CLI

Given the potential `document_title` we now
want to ask the user if the title is still
what they want to use so that we can write
the file to disk. This will involve two
paths depending on if we have an existing
potential option or not.

We will need to use `ask_for_filename` in
`confirm_filename`, so we'll write that branch
first.

```rust
let filename = match document_title {
    Some(raw_title) => {
        // confirm_filename()?
        todo!()
    }
    None => ask_for_filename(),
};
```

`rprompt` allows us to ask for a small amount
of input from the user (compared to the  much
larger input possible by passing control to
the user's editor).

We'll use `rprompt::prompt_reply_stderr` to
get a response from the user, and `.wrap_err`
to add context to the error if anything goes
wrong.

```rust
fn ask_for_filename() -> Result<String> {
    rprompt::prompt_reply_stderr(
        "\
Enter filename
> ",
    )
    .wrap_err("Failed to get filename")
}
```

We'll use the same behavior for the first
part of `confirm_filename`. We'll also
need to use our first lifetime to account
for the shared reference argument.

`match` can match against multiple values
for the same branch, so we'll take advantage
of that to handle branches for Ns and Ys, as
well as the default case. If anything goes
wrong, such as someone inputting an "a",
we'll fall through using `loop` and ask again
until we get a usable answer

```rust
fn confirm_filename(raw_title: &str) -> Result<String> {
    loop {
        // prompt defaults to uppercase character in question
        // this is a convention, not a requirement enforced by
        // the code
        let result = rprompt::prompt_reply_stderr(&format!(
            "\
current title: `{}`
Do you want a different title? (y/N): ",
            raw_title,
        ))
        .wrap_err("Failed to get input for y/n question")?;

        match result.as_str() {
            "y" | "Y" => break ask_for_filename(),
            "n" | "N" | "" => {
                // the capital N in the prompt means "default",
                // so we handle "" as input here
                break Ok(slug::slugify(raw_title));
            }
            _ => {
                // ask again because something went wrong
            }
        };
    }
}
```

While filenames can technically have spaces
in them, we're going to slugify our filenames
like urls for a few reasons. One is that
when starting out, many programmers fail to
quote filename arguments in their bash scripts,
which results in filenames with spaces being
treated as separate arguments. Another is
that this is a digital garden CLI, and
digital gardens are often stored in git,
accessed from multiple file systems, as well
as from URLs. While strictly speaking we don't
need to slugify our filenames, we will here
so as to adhere to a safer set of characters.

```
cargo add slug
```

We'll map over the `Result` from `rprompt`
which allows us to operate on the internal
value if it's `Ok`.

```rust
fn ask_for_filename() -> Result<String> {
    rprompt::prompt_reply_stderr(
        "\
Enter filename
> ",
    )
    .wrap_err("Failed to get filename")
    .map(|title| slug::slugify(title))
}
```

We'll also use slugify in `confirm_filename`

```rust
match result.as_str() {
    "y" | "Y" => break ask_for_filename(),
    "n" | "N" | "" => {
        // the capital N in the prompt means "default",
        // so we handle "" as input here
        break Ok(slug::slugify(raw_title));
    }
    _ => {
        // ask again because something went wrong
    }
};
```

The fact that `confirm_filename` and
`ask_for_filename` have the same return type
is important because the branches of a `match`
need to return the same type.

Prompting the user for input with rprompt and loop

We want to build out functionality to let the user
write into a file in their garden. To do that, we
have to know the location of their garden.

We'll start by implementing a function to get the
default garden path.

```rust
fn get_default_garden_dir() -> Result<PathBuf> {
    let user_dirs = UserDirs::new().ok_or_else(|| eyre!("Could not find home directory"))?;
    Ok(user_dirs.home_dir().join(".garden"))
}
```

This uses the user's system directories via the
`directories` crate to find their home dir. We
then add `.garden` to the home dir for the default
garden.

Ideally, we would want the user to be able to
specify their garden path. Using structopt, we
can let them specify it as a short, long, or
env var.

In our README, we'll specify how this should work.

````

```shell
GARDEN_PATH=~/github/my-digital-garden garden write
garden -p ~/github/my-digital-garden write
garden --garden_path ~/github/my-digital-garden write
```
````

And in our `Opt` struct, we can tell structopt how to
handle it. Putting this in our `Opt` struct instead of
our `Command` enum make it a global flag that can be
specified for all subcommands.

```rust
struct Opt {
    #[structopt(parse(from_os_str), short = "p", long, env)]
    garden_path: Option<PathBuf>,

    #[structopt(subcommand)]
    cmd: Command,
}
```

structopt is only handling the user input, so in
`main()` we still need to fall back to the
default if the `garden_path` is not specified.

```rust
let garden_path = match opt.garden_path {
    Some(pathbuf) => Ok(pathbuf),
    None => get_default_garden_dir().wrap_err("`garden_path` was not supplied"),
}?;
```

if we force an `Err` in `get_default_garden_dir`
We can see how the wrapped errors end up stacking.

```
Error:
   0: `garden_path` was not supplied
   1: Could not find home directory
```

We'll also change the signature of `write` to
accept the pathbuf.

```
Command::Write { title } => write(garden_path, title),
```

Note that we need to import `PathBuf`. We can also
`dbg!` the garden path and title to see their
values.

```rust
use std::path::PathBuf;

pub fn write(garden_path: PathBuf, title: Option<String>) -> Result<()> {
    dbg!(garden_path, title);
    todo!()
}
```

Adding support for global flags that apply for all subcommands with structopt

In our subcommand match we'll add a new function called
`write` to handle our `Write` subcommand. We'll pass it
the argument title and we'll "import" it from a library
called `digital_garden`. 

```rust
use digital_garden::write;

fn main() -> Result<()> {
    color_eyre::install()?;

    let opt = Opt::from_args();
    dbg!(&opt);
    match opt.cmd {
        Command::Write { title } => write(title),
    }
}
```

To create this library, add a new section in `Cargo.toml`.
We can give our library a name and set which file to treat
as the entrypoint. `src/lib.rs` is the default file for
a library crate, but we can also be explicit about what we
want to happen.

```toml
[lib]
name = "digital_garden"
path = "src/lib.rs"
```

This leaves us with two crates, a binary crate, of which we
can have any amount, and a library crate, of which we can
only have 0 or 1.

We'll create the `src/lib.rs` file with the following
contents.

```rust
mod write;

pub use write::write;
```

Rust's module system is explicit, so when we write
`mod write`, we are saying that the library `digital_garden`
has a module `write`, such that the path to the module is
`digital_garden::write`.

In our case `digital_garden::write` corresponds to a file
at `src/write.rs`.

Secondly, the `pub use write::write` says that we have a
function called `write` in the module called `write` and
that the function will be exposed from lib publicly, so
people who have the `digital_garden` library installed
will be able to use the write function as
`digital_garden::write`.

In JavaScript the closest analogue is exporting a function
from another file that exports it.

```js
export { write } from './write.js';
```

By using use, we're shortening the public path to the write
function. A private module "write" with a function "write"
also exists at `digital_garden::write::write`. If you try
to use this path, Rust will tell you there is a private
module there.

Finally, in `src/write.rs`, we can write a public function
that matches the return type of our main function, since
we're using it as the return value from our match function.

We'll accept an `Option<String>` as an argument as well,
since that's what we expect from the cli arguments.

```rust
use color_eyre::Result;

pub fn write(_title: Option<String>) -> Result<()> {
    todo!()
}
```

The purpose of creating this module path is because we
know that we're going to set up more modules for each
subcommand in the future, and we can control both the
placement of our code on disk, as well as the path users
will interact with to use our module.

Creating a library crate to support a Rust binary crate in the same package

After getting the user's input, we need to
figure out a filename to write the file out
as. We can either use the title the user
passed in, or we can try to use heuristics
to find a title from the markdown content.

We can combine the user's title from the cli
arguments (an `Option`) with the logic we
use as a heuristic for the markdown (also
an `Option`).

```rust
// use `title` if the user passed it in,
// otherwise try to find a heading in the markdown
let document_title = title.or_else(|| {
    contents
        .lines()
        .find(|v| v.starts_with("# "))
        // markdown headings are required to have `# ` with
        // at least one space
        .map(|maybe_line| maybe_line.trim_start_matches("# ").to_string())
});
```

`option.or_else()` returns the original
option if it is a `Some` value, or executes
the function to return a different `Option`
if not. So `document_title` is an
`Option<String>` either way and we've
covered all of the possible scenarios:

1. the user has passed in a title
2. the user has written content with a heading
3. the user has done neither of these

Which leaves us to our markdown heuristic.

Markdown headings are required to have `# `
with at least one space, so we can turn
`contents` into an iterator and `find` the
first line that starts with `# `.

If we find one, we want to trim `# ` off of
the heading to get just the heading content,
so we can use `map` to operate on the value
inside of the `Option` returned by `find` if
it exists.

```rust
contents
    .lines()
    .find(|v| v.starts_with("# "))
    .map(|maybe_line| maybe_line.trim_start_matches("# ").to_string())
```

Now this code works fine, but it exposes a bug
in our file handling.

If we `write_all` to the `file`, that moves the
internal cursor to the end of that content. So
when we run our code now, `contents` is
skipping the first `# ` bytes, which means our
heuristic will only find the second heading in
the file.

To fix this, we can bring in the `std::io::Seek`
trait, and seek to the beginning of the file.

```rust
let mut contents = String::new();
file.seek(SeekFrom::Start(0))?;
file.read_to_string(&mut contents)?;
```

Using the Option type in Rust to pick from multiple values that might not exist

We can match on `opt.cmd` to determine which `Command`
variants was called. This lets us specify the variants
as match criteria and also destructure the values out
to use them.

```rust
    let opt = Opt::from_args();
    dbg!(&opt);
    match opt.cmd {
        Command::Write { title } => todo!(),
    }
```

As written, we run into two issues with this code.
One is that we aren't using `title` yet. In
destructuring, we can use the placeholder (`_`) in our
[pattern](https://doc.rust-lang.org/reference/patterns.html).

```
warning: unused variable: `title`
  --> src/main.rs:32:26
   |
32 |         Command::Write { title } => todo!(),
   |                          ^^^^^ help: try ignoring the field: `title: _`
   |
   = note: `#[warn(unused_variables)]` on by default
```

```rust
fn main() -> Result<()> {
    color_eyre::install()?;

    let opt = Opt::from_args();
    dbg!(opt);
    match opt.cmd {
        Command::Write { title: _ } => todo!(),
    }
}
```

The second issue is that the `opt` variable is moved
before we try to destructure it. If we look at the
compiler output before we fixed the `title` issue we
see the value use after move pointing at `title`
specifically.

```
error[E0382]: use of moved value
m  --> src/main.rs:32:26
   |
29 |     let opt = Opt::from_args();
   |         --- move occurs because `opt` has type `Opt`, which does not implement the `Copy` trait
30 |     dbg!(opt);
   |     ---------- value moved here
31 |     match opt.cmd {
32 |         Command::Write { title } => todo!(),
   |                          ^^^^^ value used here after move
```

If we look at it after fixing the unused `title`,
we see the compiler point at `opt.cmd`.

```
error[E0382]: use of moved value: `opt.cmd`
  --> src/main.rs:31:11
   |
29 |     let opt = Opt::from_args();
   |         --- move occurs because `opt` has type `Opt`, which does not implement the `Copy` trait
30 |     dbg!(opt);
   |     ---------- value moved here
31 |     match opt.cmd {
   |           ^^^^^^^ value used here after move
```

This is because opt is moved into the `dbg` call because
it doesn't implement the `Copy` trait. Now, we could
implement or derive `Copy` for `Opt` if `Command` can
implement `Copy`, but we can not implement `Copy` for
`Command`. This is because `String` does not, and can not,
implement `Copy`, and we have a `String` in our `title`.

Without diving into the depths of `Copy`, [`Clone`](https://doc.rust-lang.org/std/clone/trait.Clone.html),
and allocation, there is something we have that already
implements `Copy`, so we don't need to.

Shared references implement `Copy`.

So instead of passing `opt` into `dbg!`, and thus using
move semantics (which are the default in Rust), we can
pass a shared reference in: `dgb!(&opt)` which lets us
use copy semantics.

The difference between move semantics and copy semantics
in this case is that we can access `opt` after passing it
to `dbg!`.

Under the hood, both a copy and a move can result in bits
being copied in memory, although this is sometimes
optimized away. -- [Copy](https://doc.rust-lang.org/std/marker/trait.Copy.html)

```rust
fn main() -> Result<()> {
    let opt = Opt::from_args();
    dbg!(&opt);
    match opt.cmd {
        Command::Write { title: _ } => todo!(),
    }
}
```

Matching structopt commands and using Rust values after move

Cargo allows us to execute a few different kinds of tests,
including integration and unit. For now we'll talk about
integration tests for our CLI. Integration tests
live in `/tests` and only have access to the public
interface of a crate.

In this case, we'll run the `garden` binary using
`assert_cmd` and assert various things about the
execution and output. For example, that the binary
exits successfully and that stderr has no output.

`cargo test` allows us to run all tests.

To restrict the number of tests that run to only the two
that work, we can use `cargo test help` to restrict
cargo to only running tests that match the keyword "help",
or use `#[ignore]` on a test we want to ignore.

The third test will be ignored because we have yet to
build out our functionality.

Integration testing Cargo binaries with assert_cmd

The StructOpt crate allows us to derive our human person functionality from our Struct definitions. 

We will create a `structop` for our `write` subcommand that will take a short and long flag for our `title` argument

---

```
cargo add structopt
```

structopt allows us to derive argument parsing functionality from our
structs. The name is a play on `struct Opt {}`. To do this we need to
`derive(StructOpt)` on our struct. In this case we have a subcommand,
so we'll set up one of the fields on the `Opt` struct to be a
`structopt(subcommand)`. This subcommand value will be an enum,
indicating that only one subcommand can be used at a time.

structopt also gives us tools to specify one of three argument types:

* positional
* short
* long

By default every argument is a positional argument, which means that in
this case if we left it as-is, the CLI would function as

```
garden write my-title
```

We want to use a flag, so we'll use structopt to generate short and long
flags for the title argument with `structopt(short, long)`. That gives
the use the option of `-t` and `--title` to specify a title.

structopt also contains some type processing, so all we need to do is
specify that title is an optional string and the flags will become
optional. That is: a user can specify or not specify a title.

```rust
struct Opt {
    #[structopt(subcommand)]
    cmd: Command,
}
enum Command {
    Write {
        #[structopt(short, long)]
        title: Option<String>,
    },
}
```

After setting up `struct Opt`, we can parse the args and use
the dbg!() macro to print them to the console so we can see
what they look like.

```rust
let opt = Opt::from_args();
dbg!(opt);
```

To do that we also need to `derive(Debug)` in addition to
structopt on both the enum and the struct.

Given input like

```
garden write
```

We will see the following output.

```rust
[src/main.rs:21] opt = Opt {
    cmd: Write {
        title: None,
    },
}
```

We can choose to `cargo build` and then `./target/debug/garden write`
or we can use `cargo run -- write`. The `--` ensures that our arguments
get passed to the CLI we're building and not `cargo run`. This is
especially relevant when passing something like `--help`.

Setting up git-like subcommands using structopt

if we run `cargo run -- --help`, we can see that structopt
thinks the name of our binary is still the package name.
We can change that with another attribute macro on our
struct.

```
digital-garden 0.1.0

USAGE:
    garden <SUBCOMMAND>

FLAGS:
    -h, --help       Prints help information
    -V, --version    Prints version information

SUBCOMMANDS:
    help     Prints this message or the help of the given subcommand(s)
    write
```

Also notice that in the help text the `help` subcommand
has some helpful output while `write` has none:

```
garden 0.1.0

USAGE:
    garden <SUBCOMMAND>

FLAGS:
    -h, --help       Prints help information
    -V, --version    Prints version information

SUBCOMMANDS:
    help     Prints this message or the help of the given subcommand(s)
    write
```

There are a number of places we can put doc comments.
We can write on the `Opt` struct for global information
about the CLI.

We can also write on each subcommand or even the options
for each subcommand.

```
/// A CLI for the growing and curation of a digital garden
///
/// Visit https://www.rustadventure.rs/garden for more!
struct Opt {
    #[structopt(subcommand)]
    cmd: Command,
}
enum Command {
    /// write something in your garden
    ///
    /// This command will open your $EDITOR, wait for you
    /// to write something, and then save the file to your
    /// garden
    Write {
        /// Optionally set a title for what you are going to write about
        #[structopt(short, long)]
        title: Option<String>,
    },
}
```

Each of these results in documentation going to the relevant
place in the CLI help text. Note especially that the first
line of doc comment for subcommands is shown as "short"
help text, while the full text is reserved for running
`--help` directly on the subcommand.

```
❯ cargo run
garden 0.1.0
A CLI for the growing and curation of a digital garden

Visit https://www.rustadventure.rs/garden for more!

USAGE:
    garden <SUBCOMMAND>

FLAGS:
    -h, --help       Prints help information
    -V, --version    Prints version information

SUBCOMMANDS:
    help     Prints this message or the help of the given subcommand(s)
    write    write something in your garden
```

```
❯ cargo run -- write --help
garden-write 0.1.0
write something in your garden

This command will open your $EDITOR, wait for you to write something, and then save the file to your garden

USAGE:
    garden write [OPTIONS]

FLAGS:
    -h, --help
            Prints help information

    -V, --version
            Prints version information

OPTIONS:
    -t, --title <title>
            Optionally set a title for what you are going to write about
```

Also note that `-h` and `--help` are *not* the same thing when it comes to structopt.

Documenting and writing helptext for Structopt CLI commands and flags

Right now we are using the `todo!()` macro which is great for simulating when our program panics. The error message that we get can be improved upon.

We will look at color-eyre that will allow us to handle the errors we receive to be more visual and human-readable. 

---
The `todo!` macro is useful and it also exposes what
happens if our application panics.

```
thread 'main' panicked at 'not yet implemented', src/main.rs:2:5
note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace
```

This could be both more readable and contain more information
while also being colored using [color_eyre](https://docs.rs/color-eyre/0.5.10/color_eyre/).

```
The application panicked (crashed).
Message:  not yet implemented
Location: src/main.rs:5

Backtrace omitted.
Run with RUST_BACKTRACE=1 environment variable to display it.
Run with RUST_BACKTRACE=full to include source snippets.
```

We'll use [cargo-edit](https://crates.io/crates/cargo-edit)
to add the package to our Cargo.toml.

```
cargo install cargo-edit
cargo add color_eyre
```

`main` can return `Result`, so we'll use `color_eyre`'s
`Result` as our return value and `color_eyre::install` to
install the default panic and error reporting hooks.
`install` returns a `Result` so we can use `?` to handle
any errors if necessary.

We haven't shown off everything that color_eyre is capable
of. In addition to panic handling, color_eyre allows us to
track additional information in the context of our errors
and include suggestions by taking advantage of distributed
[tracing](https://github.com/tokio-rs/tracing) infrastructure.

We'll see more of how this helps as we build out the CLI.

Using color_eyre and distributed tracing to yield better error messages to the user

We'll replace the `println!` macro with a call to `todo!`, which has
the additional benefit of type-checking so we won't need to finish
anything with `todo!` in the expression. Note that if we call a function
with `todo!`, we do get the `panic!` behavior.

We do have two other options for achieving the same thing,
`unimplemented!` and `panic!`. All three of these options functionally
do the same thing: they crash the program immediately.

We aren't using `panic!` because `panic!` should be used when a program
reaches an unrecoverable state. We don't have an unrecoverable state
so much as a piece of the program we intend to work on later.

For similar reasons, we aren't using `unimplemented!` because we want
to convey that this is something to work on while `unimplemented!`
doesn't necessarily mean that we intend to work on it.

Using the todo macro to typecheck unwritten code that will be implemented in the future

In `./target/debug/` we can see the binary name:
`digital-garden-steps`. This is the name of our package
and we want the actual binary that users install to be
named `garden` instead.

To do this we can change the auto-discovered `src/main.rs`
binary and change the name using a `bin` config in the
`Cargo.toml` file.

```toml
[[bin]]
name = "garden"
path = "src/main.rs"
```

Then we see `./target/debug/garden` get created when we
`cargo run` or `cargo build`.

Rename the default Cargo binary to be different than the package name

```shell
cargo init
```

By default cargo initializes a new package containing a *binary* crate.
The file that gets compiled into the binary is located at
`src/main.rs`. This is by convention and we can specify different paths
and names for binaries.

We also get a `Cargo.lock` and a `Cargo.toml`. These are similar to
JavaScript's `package.json` and `package-lock.json` or `yarn.lock`.
The `Cargo.toml` defines different features of our package including
`dependencies`, defining zero or one library crates, and defining as
many binary crates as we want.

We can run the new binary with `cargo run`.

```shell
❯ cargo run
   Compiling digital-garden-steps v0.1.0 (/digital-garden-steps)
    Finished dev [unoptimized + debuginfo] target(s) in 1.38s
     Running `target/debug/digital-garden-steps`
Hello, world!
```

Initialize a new Cargo binary crate in a new package

By writing the README first we can explore different
approaches to the user experience of our CLI. We
could think through the entire CLI right now, but we'll
leave other subcommands for later. Instead, we'll focus
on the fact that we know we will have multiple subcommands
and design the command on which all others rely: `write`.

We can come up with a first example subcommand. Note that
by doing this we are also defining the name of the binary
as `garden`.

```shell
garden write
```

When writing, users will not necessarily know the title of
what they're writing in advance, so we will not require
them to provide it. This leads us to an optional title
argument. We could have chosen to make this a positional
argument, but we made it a flag instead to delineate from
other potential future positional arguments (such as
`--message`, which we have chosen not to implement now).

```shell
garden write -t "Writing about Rust"
```

README-driven planning for a Digital Garden CLI in Rust

[Rustlings](https://github.com/rust-lang/rustlings) is a set of exercises that serves as a great introduction to the Rust language. It covers many concepts from the [Rust book](https://doc.rust-lang.org/book/) by asking you to work through sets of exercises.

This collection walks you through Rustlings in a way that explains what's going on in each exercise. We cover everything from basic types to generics and threading.

[README](https://github.com/ChristopherBiscardi/rustlings/blob/egghead/exercises/generics/README.md) for this exercise.

Rustlings generics3: Constraining generics using traits

When comparing two visually similar websites, it can often be challenging to precisely identify the subtle differences between them. To facilitate a rapid analysis of these discrepancies, a practical technique involves leveraging Chrome's integrated developer tools to capture full-page screenshots of each site. Subsequently, these screenshots can be uploaded to a platform like AI Studio. There, the AI can analyze the images and generate a report detailing the variations. This entire process, leveraging a few quick shortcuts, can be completed in under a minute, delivering a comprehensive breakdown of the differences for efficient comparison and analysis.

Quickly Compare Two Sites Using AI Studio with Chrome Full Page Screenshots

It's fairly trivial to create a React project, but there's always a big hurdle between creating it locally and making it shareable so that someone else can run it. This lesson walks you through the process of automating creating a React project locally, creating the repository where it's going to be hosted, and creating shareable links where it can be run so that you can quickly and easily create single one-off demos and shoot them over to your friends and coworkers for sharing your code ideas in a working environment.


```bash
share-react-project() {
  if [[ -z "$1" ]]; then
    echo "Usage: share-react-project <project_name>"
    return 1
  fi

  local project_name="$1"
  local github_username=$(gh api /user --jq '.login')

  echo "Creating Vite project: $project_name"
  pnpm create vite "$project_name" --template react

  cd "$project_name"

  echo "Initializing Git repository"
  git init

  echo "Adding all files to Git"
  git add .

  echo "Creating initial commit"
  git commit -m "Initial commit"

  local codesandbox_link="https://codesandbox.io/p/github/${github_username}/${project_name}"

  echo "Adding CodeSandbox link to README.md"
  echo "" >> README.md
  echo "## CodeSandbox" >> README.md
  echo "[![Open in CodeSandbox](https://assets.codesandbox.io/github/button-edit-blue.svg)](${codesandbox_link})" >> README.md

  echo "Adding README.md to Git"
  git add README.md

  echo "Committing README.md changes"
  git commit -m "Add CodeSandbox link"

  echo "Creating GitHub repository: $github_username/$project_name"
  gh repo create "$github_username/$project_name" --public

  echo "Pushing to remote 'origin'"
  git push -u origin main

  echo "Project '$project_name' created successfully!"
  echo "GitHub repository: https://github.com/$github_username/$project_name"
  echo "CodeSandbox link: $codesandbox_link"
}
```

Automate Creating a Local React Project, GitHub Repository, and Live Hosted Demo in a Single Command

[Verdaccio](https://verdaccio.org/) is a fully featured NPM registry that you can run locally on your machine. It’s a great tool for testing your release process, running end-to-end tests, and simulating real-world scenarios like deploying packages, installing them, and verifying functionality as an end user would.

Nx includes a [generator](https://nx.dev/features/generate-code) that simplifies setting up Verdaccio. To configure it, run:

```shell
npx nx g @nx/js:setup-verdaccio   
```

This command installs the necessary NPM packages and creates a `project.json` file with a `local-registry` target. To start the local registry, open a new terminal window and run:

```shell
npx nx local-registry
```

This will:
- Launch the Verdaccio registry.
- Configure NPM to point to the local Verdaccio server at `http://localhost:4873`.

> **Note:** A `project.json` file provides an advanced way to define scripts, offering more flexibility than a traditional `package.json` for managing complex targets.

Setup local Verdaccio server to release NPM packages

Learn how to spin up a local NPM registry powered by Verdaccio to test deploy your NPM packages.

In TypeScript, developers often begin by defining the structure of their data using type definitions or interfaces, which is a powerful way to ensure type safety. However, as applications grow and become more complex, simply defining the shape of an object might not be enough to guarantee its consistent creation and behavior throughout the codebase. This often leads to situations where objects that are intended to be of a certain "type" might be missing crucial properties or have incorrect data, which can be difficult to track down and debug.

This lesson tackles the question of when and why to move beyond basic type definitions and embrace classes in TypeScript. It demonstrates how classes provide a more robust mechanism for defining object structure, enforcing type constraints, and ensuring consistent object creation. By establishing a clear blueprint for objects, classes not only improve compile-time type safety but also offer runtime benefits and better code organization, ultimately helping developers avoid common pitfalls associated with loosely structured objects in larger TypeScript projects.

Stop Avoiding Classes in TypeScript

Karabiner isn't only for your keyboard. It can also hijack your mouse buttons and enable them to be similar to layers on your keyboard, where holding down a mouse button can allow you to tap keys on your keyboard to trigger commands and macros that can completely revolutionize your workflows. For example, you can hold down the right mouse button and tap on R to go to references in VS Code. Or hold down the right mouse button and tap the left mouse button to chop up videos and Screenflow.

This completely unlocks a whole new world of possibilities and use cases for your mouse as you can hover your mouse over anywhere on the page. And just tapping keys on your keyboard allows you to trigger mouse actions, to trigger keyboard actions, or to trigger macros and applications and terminal commands. and anything that your imagination can come up with. 

Karabiner: Rethinking Right-Click as a Macro Command Center

Make an HTML table more readable on mobile devices by using the ::before pseudo-element. We add labels to each cell, so they appear like cards when the table is viewed on smaller screens. The ::before content is set using a data-label attribute for each cell to enhance mobile viewability without horizontal scrolling.



Create a mobile friendly table with the before pseudo-element

Learn to use CSS ::before pseudo-element for mobile-friendly HTML tables. Add labels to cells for enhanced readability on mobile, avoiding horizontal scroll.

Any app of a decent size has event flows and messages being passed around. At a certain point it becomes complicated to explain it through prose and you want to turn towards diagrams. Now setting aside the time to create diagrams that accurately describe what's happening in your codebase can be quite time consuming. Luckily, with today's AI tools, we can now just do basic walkthroughs with rough recordings over codebase dictating what's going on along the way and then upload that to tools like AI Studio and then ask it to generate diagrams in a text-based format such as Mermaid that will then generate the flowcharts and diagrams for us. So this video walks us through this process of recording a rough video, uploading it to AI Studio and then asking AI Studio to generate the proper Mermaid diagram syntax.

Generate Mermaid Flow Chart Diagrams with Gemini 2.0 from Rough Screen Recordings

I'm a diehard Karabiner user and anytime I start doing something repetitively I always move it into my Karabiner configuration. Sometimes I'll fall into scenarios where I want to trigger a command, but I also want to know if that command succeeded or failed. Since Karabiner can trigger any command, setting up the command is fairly straightforward, but knowing whether it succeeded or failed became much more difficult. Luckily for me there is a package called terminal-notifier that you can install from homebrew and you can pipe the output of your command to terminal-notifier. And have a seamless way of triggering your keyboard shortcut which runs a command and you can be notified of the results.

Use Karabiner to Trigger a Terminal Command and Get Notified of the Results

There are a lot of scenarios when inspecting a site in Chrome where you don't want any click events to fire and you don't want any scripts to run. Or maybe something is animating in and out of the page and you want to capture it at a certain moment. This is a great use case for pausing script execution, which is kind of using the debugger manually by going into the Chrome DevTools and the Sources tab and clicking the pause button to essentially pause the entire page. This will give you a chance to inspect any of the elements and styles you want to inspect. And you don't have to worry about fire and click events or anything that might interrupt your investigation into the elements and styles that you want to find.

Pause Script Execution in Chrome to Easily Inspect Elements

Gemini 2.0 has a context window of a million tokens, and this means that you can upload hundreds of files and allow it to inspect and analyze massive refactors across entire code bases. 

This lesson demonstrates concatenating an entire code base into a single file and then uploading it to AI Studio. Once within AI Studio, we ask it to find the types of tasks that it can evaluate for us. Then we select one of the tasks and ask it to generate instructions for that task. Once those instructions are complete, we then turn them over to Windsurf's Cascade agent, and we allow Windsurf's Cascade to do all of the work for us as we sit back, relax, and let the AI do our jobs.

Chris Biscardi

Create a Digital Garden CLI with Rust

Featured Courses

Learning Rust by Working Through the Rustlings Exercises

Building an OpenGraph image generation API with Cloudinary, Netlify Functions, and React

Jamstack

Composable Gatsby Themes

Building Websites with MDX and Gatsby

Building a Serverless JAMStack Todo app with Netlify, Gatsby, GraphQL, and FaunaDB

Database

Intro to DynamoDB

Converting a Serverless App to run on AWS Lambda and DynamoDB with Serverless Framework

DynamoDB: The Node.js DocumentClient

Search Results

Creating a Digital Garden CLI with Rust

Abstracting test utilities inside integration test files

Using owo_colors Extension Traits to colorize terminal output

Checking for file existence with PathBuf to ensure unique filenames

Using assert_fs and predicates to integration test with a real temporary file system

Passing control to the user's favorite editor (such as VSCode) from the CLI

Prompting the user for input with rprompt and loop

Adding support for global flags that apply for all subcommands with structopt

Creating a library crate to support a Rust binary crate in the same package

Using the Option type in Rust to pick from multiple values that might not exist

Matching structopt commands and using Rust values after move

Integration testing Cargo binaries with assert_cmd

Setting up git-like subcommands using structopt

Documenting and writing helptext for Structopt CLI commands and flags

Using color_eyre and distributed tracing to yield better error messages to the user

Using the todo macro to typecheck unwritten code that will be implemented in the future

Rename the default Cargo binary to be different than the package name

Initialize a new Cargo binary crate in a new package

README-driven planning for a Digital Garden CLI in Rust

Learning Rust by Working Through the Rustlings Exercises

Rustlings generics3: Constraining generics using traits