Allow plugins to report their own version and store it in the registry (#12883)

# Description

This allows plugins to report their version (and potentially other
metadata in the future). The version is shown in `plugin list` and in
`version`.

The metadata is stored in the registry file, and reflects whatever was
retrieved on `plugin add`, not necessarily the running binary. This can
help you to diagnose if there's some kind of mismatch with what you
expect. We could potentially use this functionality to show a warning or
error if a plugin being run does not have the same version as what was
in the cache file, suggesting `plugin add` be run again, but I haven't
done that at this point.

It is optional, and it requires the plugin author to make some code
changes if they want to provide it, since I can't automatically
determine the version of the calling crate or anything tricky like that
to do it.

Example:

```
> plugin list | select name version is_running pid
╭───┬────────────────┬─────────┬────────────┬─────╮
│ # │      name      │ version │ is_running │ pid │
├───┼────────────────┼─────────┼────────────┼─────┤
│ 0 │ example        │ 0.93.1  │ false      │     │
│ 1 │ gstat          │ 0.93.1  │ false      │     │
│ 2 │ inc            │ 0.93.1  │ false      │     │
│ 3 │ python_example │ 0.1.0   │ false      │     │
╰───┴────────────────┴─────────┴────────────┴─────╯
```

cc @maxim-uvarov (he asked for it)

# User-Facing Changes

- `plugin list` gets a `version` column
- `version` shows plugin versions when available
- plugin authors *should* add `fn metadata()` to their `impl Plugin`,
but don't have to

# Tests + Formatting

Tested the low level stuff and also the `plugin list` column.

# After Submitting
- [ ] update plugin guide docs
- [ ] update plugin protocol docs (`Metadata` call & response)
- [ ] update plugin template (`fn metadata()` should be easy)
- [ ] release notes

crates/nu-plugin-engine/src/init.rs

@@ -252,7 +252,7 @@ pub fn load_plugin_registry_item(
         })?;
 
     match &plugin.data {
-        PluginRegistryItemData::Valid { commands } => {
+        PluginRegistryItemData::Valid { metadata, commands } => {
             let plugin = add_plugin_to_working_set(working_set, &identity)?;
 
             // Ensure that the plugin is reset. We're going to load new signatures, so we want to
@@ -260,6 +260,9 @@ pub fn load_plugin_registry_item(
             // doesn't.
             plugin.reset()?;
 
+            // Set the plugin metadata from the file
+            plugin.set_metadata(Some(metadata.clone()));
+
             // Create the declarations from the commands
             for signature in commands {
                 let decl = PluginDeclaration::new(plugin.clone(), signature.clone());

crates/nu-plugin-engine/src/interface/mod.rs

@@ -11,8 +11,8 @@ use nu_plugin_protocol::{
     PluginOutput, ProtocolInfo, StreamId, StreamMessage,
 };
 use nu_protocol::{
-    ast::Operator, CustomValue, IntoSpanned, PipelineData, PluginSignature, ShellError, Span,
-    Spanned, Value,
+    ast::Operator, CustomValue, IntoSpanned, PipelineData, PluginMetadata, PluginSignature,
+    ShellError, Span, Spanned, Value,
 };
 use std::{
     collections::{btree_map, BTreeMap},
@@ -716,6 +716,7 @@ impl PluginInterface {
 
         // Convert the call into one with a header and handle the stream, if necessary
         let (call, writer) = match call {
+            PluginCall::Metadata => (PluginCall::Metadata, Default::default()),
             PluginCall::Signature => (PluginCall::Signature, Default::default()),
             PluginCall::CustomValueOp(value, op) => {
                 (PluginCall::CustomValueOp(value, op), Default::default())
@@ -913,6 +914,17 @@ impl PluginInterface {
         self.receive_plugin_call_response(result.receiver, context, result.state)
     }
 
+    /// Get the metadata from the plugin.
+    pub fn get_metadata(&self) -> Result<PluginMetadata, ShellError> {
+        match self.plugin_call(PluginCall::Metadata, None)? {
+            PluginCallResponse::Metadata(meta) => Ok(meta),
+            PluginCallResponse::Error(err) => Err(err.into()),
+            _ => Err(ShellError::PluginFailedToDecode {
+                msg: "Received unexpected response to plugin Metadata call".into(),
+            }),
+        }
+    }
+
     /// Get the command signatures from the plugin.
     pub fn get_signature(&self) -> Result<Vec<PluginSignature>, ShellError> {
         match self.plugin_call(PluginCall::Signature, None)? {
@@ -1206,6 +1218,7 @@ impl CurrentCallState {
         source: &PluginSource,
     ) -> Result<(), ShellError> {
         match call {
+            PluginCall::Metadata => Ok(()),
             PluginCall::Signature => Ok(()),
             PluginCall::Run(CallInfo { call, .. }) => self.prepare_call_args(call, source),
             PluginCall::CustomValueOp(_, op) => {

crates/nu-plugin-engine/src/interface/tests.rs

@@ -18,7 +18,7 @@ use nu_protocol::{
     ast::{Math, Operator},
     engine::Closure,
     ByteStreamType, CustomValue, IntoInterruptiblePipelineData, IntoSpanned, PipelineData,
-    PluginSignature, ShellError, Span, Spanned, Value,
+    PluginMetadata, PluginSignature, ShellError, Span, Spanned, Value,
 };
 use serde::{Deserialize, Serialize};
 use std::{
@@ -1019,6 +1019,25 @@ fn start_fake_plugin_call_responder(
         .expect("failed to spawn thread");
 }
 
+#[test]
+fn interface_get_metadata() -> Result<(), ShellError> {
+    let test = TestCase::new();
+    let manager = test.plugin("test");
+    let interface = manager.get_interface();
+
+    start_fake_plugin_call_responder(manager, 1, |_| {
+        vec![ReceivedPluginCallMessage::Response(
+            PluginCallResponse::Metadata(PluginMetadata::new().with_version("test")),
+        )]
+    });
+
+    let metadata = interface.get_metadata()?;
+
+    assert_eq!(Some("test"), metadata.version.as_deref());
+    assert!(test.has_unconsumed_write());
+    Ok(())
+}
+
 #[test]
 fn interface_get_signature() -> Result<(), ShellError> {
     let test = TestCase::new();

crates/nu-plugin-engine/src/persistent.rs

@@ -7,7 +7,7 @@ use super::{PluginInterface, PluginSource};
 use nu_plugin_core::CommunicationMode;
 use nu_protocol::{
     engine::{EngineState, Stack},
-    PluginGcConfig, PluginIdentity, RegisteredPlugin, ShellError,
+    PluginGcConfig, PluginIdentity, PluginMetadata, RegisteredPlugin, ShellError,
 };
 use std::{
     collections::HashMap,
@@ -31,6 +31,8 @@ pub struct PersistentPlugin {
 struct MutableState {
     /// Reference to the plugin if running
     running: Option<RunningPlugin>,
+    /// Metadata for the plugin, e.g. version.
+    metadata: Option<PluginMetadata>,
     /// Plugin's preferred communication mode (if known)
     preferred_mode: Option<PreferredCommunicationMode>,
     /// Garbage collector config
@@ -59,6 +61,7 @@ impl PersistentPlugin {
             identity,
             mutable: Mutex::new(MutableState {
                 running: None,
+                metadata: None,
                 preferred_mode: None,
                 gc_config,
             }),
@@ -268,6 +271,16 @@ impl RegisteredPlugin for PersistentPlugin {
         self.stop_internal(true)
     }
 
+    fn metadata(&self) -> Option<PluginMetadata> {
+        self.mutable.lock().ok().and_then(|m| m.metadata.clone())
+    }
+
+    fn set_metadata(&self, metadata: Option<PluginMetadata>) {
+        if let Ok(mut mutable) = self.mutable.lock() {
+            mutable.metadata = metadata;
+        }
+    }
+
     fn set_gc_config(&self, gc_config: &PluginGcConfig) {
         if let Ok(mut mutable) = self.mutable.lock() {
             // Save the new config for future calls