Reorganize plugin API around commands (#12170)

[Context on
Discord](https://discord.com/channels/601130461678272522/855947301380947968/1216517833312309419)

# Description
This is a significant breaking change to the plugin API, but one I think
is worthwhile. @ayax79 mentioned on Discord that while trying to start
on a dataframes plugin, he was a little disappointed that more wasn't
provided in terms of code organization for commands, particularly since
there are *a lot* of `dfr` commands.

This change treats plugins more like miniatures of the engine, with
dispatch of the command name being handled inherently, each command
being its own type, and each having their own signature within the trait
impl for the command type rather than having to find a way to centralize
it all into one `Vec`.

For the example plugins that have multiple commands, I definitely like
how this looks a lot better. This encourages doing code organization the
right way and feels very good.

For the plugins that have only one command, it's just a little bit more
boilerplate - but still worth it, in my opinion.

The `Box<dyn PluginCommand<Plugin = Self>>` type in `commands()` is a
little bit hairy, particularly for Rust beginners, but ultimately not so
bad, and it gives the desired flexibility for shared state for a whole
plugin + the individual commands.

# User-Facing Changes
Pretty big breaking change to plugin API, but probably one that's worth
making.

```rust
use nu_plugin::*;
use nu_protocol::{PluginSignature, PipelineData, Type, Value};

struct LowercasePlugin;
struct Lowercase;

// Plugins can now have multiple commands
impl PluginCommand for Lowercase {
    type Plugin = LowercasePlugin;

    // The signature lives with the command
    fn signature(&self) -> PluginSignature {
        PluginSignature::build("lowercase")
            .usage("Convert each string in a stream to lowercase")
            .input_output_type(Type::List(Type::String.into()), Type::List(Type::String.into()))
    }

    // We also provide SimplePluginCommand which operates on Value like before
    fn run(
        &self,
        plugin: &LowercasePlugin,
        engine: &EngineInterface,
        call: &EvaluatedCall,
        input: PipelineData,
    ) -> Result<PipelineData, LabeledError> {
        let span = call.head;
        Ok(input.map(move |value| {
            value.as_str()
                .map(|string| Value::string(string.to_lowercase(), span))
                // Errors in a stream should be returned as values.
                .unwrap_or_else(|err| Value::error(err, span))
        }, None)?)
    }
}

// Plugin now just has a list of commands, and the custom value op stuff still goes here
impl Plugin for LowercasePlugin {
    fn commands(&self) -> Vec<Box<dyn PluginCommand<Plugin=Self>>> {
        vec![Box::new(Lowercase)]
    }
}

fn main() {
    serve_plugin(&LowercasePlugin{}, MsgPackSerializer)
}
```

Time this however you like - we're already breaking stuff for 0.92, so
it might be good to do it now, but if it feels like a lot all at once,
it could wait.

# Tests + Formatting
- 🟢 `toolkit fmt`
- 🟢 `toolkit clippy`
- 🟢 `toolkit test`
- 🟢 `toolkit test stdlib`

# After Submitting
- [ ] Update examples in the book
- [x] Fix #12088 to match - this change would actually simplify it a
lot, because the methods are currently just duplicated between `Plugin`
and `StreamingPlugin`, but they only need to be on `Plugin` with this
change

crates/nu_plugin_example/src/commands/mod.rs

@@ -0,0 +1,13 @@
+mod nu_example_1;
+mod nu_example_2;
+mod nu_example_3;
+mod nu_example_config;
+mod nu_example_disable_gc;
+mod nu_example_env;
+
+pub use nu_example_1::NuExample1;
+pub use nu_example_2::NuExample2;
+pub use nu_example_3::NuExample3;
+pub use nu_example_config::NuExampleConfig;
+pub use nu_example_disable_gc::NuExampleDisableGc;
+pub use nu_example_env::NuExampleEnv;

crates/nu_plugin_example/src/commands/nu_example_1.rs

@@ -0,0 +1,43 @@
+use nu_plugin::{EngineInterface, EvaluatedCall, LabeledError, SimplePluginCommand};
+use nu_protocol::{Category, PluginExample, PluginSignature, SyntaxShape, Value};
+
+use crate::Example;
+
+pub struct NuExample1;
+
+impl SimplePluginCommand for NuExample1 {
+    type Plugin = Example;
+
+    fn signature(&self) -> PluginSignature {
+        // The signature defines the usage of the command inside Nu, and also automatically
+        // generates its help page.
+        PluginSignature::build("nu-example-1")
+            .usage("PluginSignature test 1 for plugin. Returns Value::Nothing")
+            .extra_usage("Extra usage for nu-example-1")
+            .search_terms(vec!["example".into()])
+            .required("a", SyntaxShape::Int, "required integer value")
+            .required("b", SyntaxShape::String, "required string value")
+            .switch("flag", "a flag for the signature", Some('f'))
+            .optional("opt", SyntaxShape::Int, "Optional number")
+            .named("named", SyntaxShape::String, "named string", Some('n'))
+            .rest("rest", SyntaxShape::String, "rest value string")
+            .plugin_examples(vec![PluginExample {
+                example: "nu-example-1 3 bb".into(),
+                description: "running example with an int value and string value".into(),
+                result: None,
+            }])
+            .category(Category::Experimental)
+    }
+
+    fn run(
+        &self,
+        plugin: &Example,
+        _engine: &EngineInterface,
+        call: &EvaluatedCall,
+        input: &Value,
+    ) -> Result<Value, LabeledError> {
+        plugin.print_values(1, call, input)?;
+
+        Ok(Value::nothing(call.head))
+    }
+}

crates/nu_plugin_example/src/commands/nu_example_2.rs

@@ -0,0 +1,47 @@
+use nu_plugin::{EngineInterface, EvaluatedCall, LabeledError, SimplePluginCommand};
+use nu_protocol::{record, Category, PluginSignature, SyntaxShape, Value};
+
+use crate::Example;
+
+pub struct NuExample2;
+
+impl SimplePluginCommand for NuExample2 {
+    type Plugin = Example;
+
+    fn signature(&self) -> PluginSignature {
+        // The signature defines the usage of the command inside Nu, and also automatically
+        // generates its help page.
+        PluginSignature::build("nu-example-2")
+            .usage("PluginSignature test 2 for plugin. Returns list of records")
+            .required("a", SyntaxShape::Int, "required integer value")
+            .required("b", SyntaxShape::String, "required string value")
+            .switch("flag", "a flag for the signature", Some('f'))
+            .optional("opt", SyntaxShape::Int, "Optional number")
+            .named("named", SyntaxShape::String, "named string", Some('n'))
+            .rest("rest", SyntaxShape::String, "rest value string")
+            .category(Category::Experimental)
+    }
+
+    fn run(
+        &self,
+        plugin: &Example,
+        _engine: &EngineInterface,
+        call: &EvaluatedCall,
+        input: &Value,
+    ) -> Result<Value, LabeledError> {
+        plugin.print_values(2, call, input)?;
+
+        let vals = (0..10i64)
+            .map(|i| {
+                let record = record! {
+                    "one" => Value::int(i, call.head),
+                    "two" => Value::int(2 * i, call.head),
+                    "three" => Value::int(3 * i, call.head),
+                };
+                Value::record(record, call.head)
+            })
+            .collect();
+
+        Ok(Value::list(vals, call.head))
+    }
+}

crates/nu_plugin_example/src/commands/nu_example_3.rs

@@ -0,0 +1,40 @@
+use nu_plugin::{EngineInterface, EvaluatedCall, LabeledError, SimplePluginCommand};
+use nu_protocol::{Category, PluginSignature, SyntaxShape, Value};
+
+use crate::Example;
+
+pub struct NuExample3;
+
+impl SimplePluginCommand for NuExample3 {
+    type Plugin = Example;
+
+    fn signature(&self) -> PluginSignature {
+        // The signature defines the usage of the command inside Nu, and also automatically
+        // generates its help page.
+        PluginSignature::build("nu-example-3")
+            .usage("PluginSignature test 3 for plugin. Returns labeled error")
+            .required("a", SyntaxShape::Int, "required integer value")
+            .required("b", SyntaxShape::String, "required string value")
+            .switch("flag", "a flag for the signature", Some('f'))
+            .optional("opt", SyntaxShape::Int, "Optional number")
+            .named("named", SyntaxShape::String, "named string", Some('n'))
+            .rest("rest", SyntaxShape::String, "rest value string")
+            .category(Category::Experimental)
+    }
+
+    fn run(
+        &self,
+        plugin: &Example,
+        _engine: &EngineInterface,
+        call: &EvaluatedCall,
+        input: &Value,
+    ) -> Result<Value, LabeledError> {
+        plugin.print_values(3, call, input)?;
+
+        Err(LabeledError {
+            label: "ERROR from plugin".into(),
+            msg: "error message pointing to call head span".into(),
+            span: Some(call.head),
+        })
+    }
+}

crates/nu_plugin_example/src/commands/nu_example_config.rs

@@ -0,0 +1,38 @@
+use nu_plugin::{EngineInterface, EvaluatedCall, LabeledError, SimplePluginCommand};
+use nu_protocol::{Category, PluginSignature, Type, Value};
+
+use crate::Example;
+
+pub struct NuExampleConfig;
+
+impl SimplePluginCommand for NuExampleConfig {
+    type Plugin = Example;
+
+    fn signature(&self) -> PluginSignature {
+        PluginSignature::build("nu-example-config")
+            .usage("Show plugin configuration")
+            .extra_usage("The configuration is set under $env.config.plugins.example")
+            .category(Category::Experimental)
+            .search_terms(vec!["example".into(), "configuration".into()])
+            .input_output_type(Type::Nothing, Type::Table(vec![]))
+    }
+
+    fn run(
+        &self,
+        _plugin: &Example,
+        engine: &EngineInterface,
+        call: &EvaluatedCall,
+        _input: &Value,
+    ) -> Result<Value, LabeledError> {
+        let config = engine.get_plugin_config()?;
+        match config {
+            Some(config) => Ok(config.clone()),
+            None => Err(LabeledError {
+                label: "No config sent".into(),
+                msg: "Configuration for this plugin was not found in `$env.config.plugins.example`"
+                    .into(),
+                span: Some(call.head),
+            }),
+        }
+    }
+}

crates/nu_plugin_example/src/commands/nu_example_disable_gc.rs

@@ -0,0 +1,52 @@
+use nu_plugin::{EngineInterface, EvaluatedCall, LabeledError, SimplePluginCommand};
+use nu_protocol::{Category, PluginSignature, Value};
+
+use crate::Example;
+
+pub struct NuExampleDisableGc;
+
+impl SimplePluginCommand for NuExampleDisableGc {
+    type Plugin = Example;
+
+    fn signature(&self) -> PluginSignature {
+        PluginSignature::build("nu-example-disable-gc")
+            .usage("Disable the plugin garbage collector for `example`")
+            .extra_usage(
+                "\
+Plugins are garbage collected by default after a period of inactivity. This
+behavior is configurable with `$env.config.plugin_gc.default`, or to change it
+specifically for the example plugin, use
+`$env.config.plugin_gc.plugins.example`.
+
+This command demonstrates how plugins can control this behavior and disable GC
+temporarily if they need to. It is still possible to stop the plugin explicitly
+using `plugin stop example`.",
+            )
+            .search_terms(vec![
+                "example".into(),
+                "gc".into(),
+                "plugin_gc".into(),
+                "garbage".into(),
+            ])
+            .switch("reset", "Turn the garbage collector back on", None)
+            .category(Category::Experimental)
+    }
+
+    fn run(
+        &self,
+        _plugin: &Example,
+        engine: &EngineInterface,
+        call: &EvaluatedCall,
+        _input: &Value,
+    ) -> Result<Value, LabeledError> {
+        let disabled = !call.has_flag("reset")?;
+        engine.set_gc_disabled(disabled)?;
+        Ok(Value::string(
+            format!(
+                "The plugin garbage collector for `example` is now *{}*.",
+                if disabled { "disabled" } else { "enabled" }
+            ),
+            call.head,
+        ))
+    }
+}

crates/nu_plugin_example/src/commands/nu_example_env.rs

@@ -0,0 +1,49 @@
+use nu_plugin::{EngineInterface, EvaluatedCall, LabeledError, SimplePluginCommand};
+use nu_protocol::{Category, PluginSignature, SyntaxShape, Type, Value};
+
+use crate::Example;
+
+pub struct NuExampleEnv;
+
+impl SimplePluginCommand for NuExampleEnv {
+    type Plugin = Example;
+
+    fn signature(&self) -> PluginSignature {
+        PluginSignature::build("nu-example-env")
+            .usage("Get environment variable(s)")
+            .extra_usage("Returns all environment variables if no name provided")
+            .category(Category::Experimental)
+            .optional(
+                "name",
+                SyntaxShape::String,
+                "The name of the environment variable to get",
+            )
+            .switch("cwd", "Get current working directory instead", None)
+            .search_terms(vec!["example".into(), "env".into()])
+            .input_output_type(Type::Nothing, Type::Any)
+    }
+
+    fn run(
+        &self,
+        _plugin: &Example,
+        engine: &EngineInterface,
+        call: &EvaluatedCall,
+        _input: &Value,
+    ) -> Result<Value, LabeledError> {
+        if call.has_flag("cwd")? {
+            // Get working directory
+            Ok(Value::string(engine.get_current_dir()?, call.head))
+        } else if let Some(name) = call.opt::<String>(0)? {
+            // Get single env var
+            Ok(engine
+                .get_env_var(name)?
+                .unwrap_or(Value::nothing(call.head)))
+        } else {
+            // Get all env vars, converting the map to a record
+            Ok(Value::record(
+                engine.get_env_vars()?.into_iter().collect(),
+                call.head,
+            ))
+        }
+    }
+}