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


Using Cursor Chat, you can easily reference an entire directory of files and ask it to generate anything based on those files. This opens up the possibility of using your current code as a reference guide to create new code that follows existing patterns. With this approach, the result can be a polished prompt you can use with any AI to generate consistent and reliable output.

Focus less on crafting the perfect prompt upfront - what matters most is testing and iterating based on the AI's responses. The more results you see from the prompt, the more you can reinforce the good results and prune out the bad results until your prompt is polished enough that you can rely on the prompt to give you consistent quality results.


Create AI Prompts Based on a Directory of Files


With Cursor's "Composer" feature, you can select and entire directory and make changes to every file. This video walks through the process of selecting a folder and refactoring all the files from JavaScript to TypeScript. It also demonstrates other tips around generating terminal commands and customizing your main Cursor "Rules for AI".


Run an AI Refactor on Every File in a Directory with Cursor


This lesson breaks down the concept of asynchronous iterators and generators in JavaScript. Using the Node.js glob function as a practical example, you'll learn how Array.fromAsync facilitates the creation of arrays from asynchronous iterables and how generators can improve performance in file processing tasks.

Efficient File Processing in Node.js with Async Generators and Array.fromAsync

Learn the concept of asynchronous iterators and generators in JavaScript and Node.js Array.fromAsync


With the introduction of Svelte 5, the Svelte team has created a CLI, `sv`, that unifies all the tasks that previously spread across a handful of CLIS (create, add plugins, and migrate).

This lesson will create a Svelte project using the new `sv` CLI and build a counter component to showcase the new `$state`, `$derived`, and `$effect` runes that ship with the new version.



Get Started with Svelte 5 using the sv CLI

You'll create a SvelteKit project using the sv CLI and build a counter component showcasing Svelte $state, $derived, and $effect runes.



pnpm ships with a streamlined, easy way of managing Node.js versions for youself and your team. This video demonstrates why pnpm uses a specific version of Node.js, how to configure it globally, and how to set up your project so that anyone who is running your project will automatically use the same version of Node.js even if that version of Node.js is not installed.


use pnpm as a Node.js version manager

How you build with Angular has changed quite a lot over the years.

For example, the `inject` function was introduced in version 14 but you might still be familiar with Angular's constructor injection.

Similarly, structural directives like `ngif` or `ngfor` have been replaced with `@if` and `@for` blocks since version 17 and beyond.

These are patterns that need to be adjusted if you want to stay up-to-date with the latest Angular has to provide.

Luckily, Angular gives you great tools in the form of a migration CLI for supporting your migration efforts as you incrementally update your App from older version features and patterns. 

When you're done with this course you'll know how to target specific features, folders, and files to migrate to the latest Angular version.

You'll learn how to 'migrate':
- Structural directives with control flow syntax
- Constructor dependency inject to inject function
- Make components standalone
- Lazy load routes
- Input/Output decorators to signal-based API


Angular Migrations in Practice

Migrate old Angular patterns for version 18 and beyond

When we import assets in React components outside of the `public` folder that Nitro reads for assets by default when running the development server we need to tell Nitro how to find them with the `devProxy` configuration option.

```typescript
export default defineNitroConfig({
  renderer: './renderer.ts',
  devProxy: {
    '/app/assets': 'http://localhost:5173/app/assets'
  }
})
```

This is ultimately inadequate in scenarios where you want to import assets arbitrarily and have them "just work" but works in a pinch.



Use devProxy in Nitro Config to Serve Static Imported Assets in Dev Mode via Vite

Learn how to use devProxy in Nitro Config with Vite to serve static assets in React components in dev mode.

Start with a basic Vite React TypeScript app and enhance it for production use by integrating Nitro as the server. 

This requires a custom Vite plugin for nitro as well as a custom renderer and manually creating Nitro config.

The other way to approach this would be to add Vite to a Nitro app instead. Same basic result.

The [Nitro config reference](https://nitro.unjs.io/config) is a great read of you'd like to explore more options.


Configure a Vite React TypeScript Application on a Basic Nitro Server

Configure a Vite React TypeScript app by integrating Nitro for production, using custom plugins, renderers, and configs.

Quick Get Started style introduction to Vite using `pnpm create vite` with the React TypeScript template.

See [more in the official docs](https://vite.dev/guide/).

Create a Vite App with the React TypeScript Preset

Quick guide to start a Vite app using React TypeScript template with pnpm.

Over the years, your application have grown huge. Sometimes, really HUGE.

Many developers have contributed to the codebase. One day they pushed one coding style, a different one another day. Sometimes even different patterns and solutions for similar problems.

You want to keep your codebase consistent. In the Angular ecosystem, there were well established patterns for doing things the right way ™️. But the old solutions are being challenged by signal-based approach.

Eventually, you ask yourself the key question: **Should you integrate with the NEW solutions or stick to the battle-tested ones, but already considered LEGACY**?

That's a very good question indeed. Don't rush with architectural decisions 🤓.

## First, think of what problems you want to solve by introducing the change.

Do you have 1k LoC Angular components? Maybe even 2k? Do you and your team enjoy working with these? 😏

Where does the **domain logic and state management code** belong to - do you have a clear guidance on which code should be put where? Have you spot that different devs implement similar features in totally different ways?

Do you keep on asking the same questions over and over again: **whether this certain piece of code** should be **imperative** (plain old object properties and variables) or **reactive** (streams)? It'd be nice to keep all thinga reactive, but more often than not, it introduces complexity.

## Second, think of long-term consequences.

You are going to have more than one way to **manage the state**. But is that really an issue? If your codebase is modular, separate modules should not depend on each other in any way. Inner abstractions of one should be invisible to the other, etc.

You are going to introduce a **new tool**. On one hand, you need to learn it, and so does your team. But on the other hand, it's a breathe of fresh air. And it's useful to question the way you've been doing things so far. Maybe there's a more effective way?

You are going to embrace signal-based APIs. And that means taking taking advantage of Zoneless Angular. This means using all modern Angular APIs. And you know that signals are the future. Why would you want to stick to the **less performant, less type-safe, less flexible and, objectively, less effective solutions**?

## Finally, plan your INCREMENTAL integration.

INCREMENTAL is the absolute keyword here. You don't want to tell your PM you need to stop delivering features because of a refactor.

Actually, there's no need for a "refactor". Just pick the first new feature to be implemented. Or pick the one that needs to be extended.

NGRX Signal Store allows you to create both very simple & small stores, as well as bigger ones. **Composition** is the key here.

**Start simple**.

Create a `withState` section with the signals that hold the state. That's already reactive. And relatively simple.

```ts
const initialState: CartState = {
  items: ...,
  rebate: ...,
}

export const CartStore = signalStore(
  withState(initialState)
);
```

Create a `withMethods` section to provide ways to change the state:

```ts
export const CartStore = signalStore(
  ...
  withMethods((store) => ({
    addItem(item: ShoppingItem): void {
      patchState(store, (state) => ({ items: [ ...state.items, item ] }));
    },
    ...
);
```

Create a `withComputed` section to provide all derived computations:

```ts
export const CartStore = signalStore(
  ...
  withComputed(({ items }) => ({
    totalPrice: computed(() => items().reduce(...))
    ...
);
```

**Start simple**.

Now you can (literally) **`inject` this code into your existing solution**. All you need is to inject your brand new NGRX Signal Store implementation into a component, or a service:

```ts
@Injectable()
class ExistingBigService {
  cartStore = inject(CartStore)
  //...  
}
```

and that's it! What's beatiful is that NGRX Signal Store should remain an implementation details (of a component, service, etc). It **shouldn't leak outside to the entire application unintentionally**. Small NGRX Signal Stores help us to **keep logic more modular**.

Don't hesitate - give NGRX Signal Store a try! Start with the [_**Scalable Signals Angular Architecture with NGRX Signal Store**_](https://egghead.io/courses/scalable-signals-angular-architecture-with-ngrx-signal-store-a33abd39) course now!

Integrating NGRX Signal Store with an existing Angular application

Integrate NGRX Signal Store into your Angular app incrementally for modular, reactive state management. Improve consistency and performance with modern APIs.

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