feat(complete): Add dynamic completion for nushell

Adds an implementation of dynamic completion to 
`clap_complete_nushell` under the `unstable-dynamic` feature flag.

The user runs
```nushell
COMPLETE=nushell the-clap-tool | save --append --raw $nu.env-path
```
and the dynamic completion will emit an "auto-update" script into
the user's `env.nu`. The auto-update script snippet will
maintain a script in the user's autoload directory that
installs a command-scoped completer.

Author: chklauser

Cargo.lock

@@ -36,13 +36,15 @@ clap = { path = "../", version = "4.0.0", default-features = false, features = [
 clap_complete = { path = "../clap_complete", version = "4.5.51" }
 completest = { version = "0.4.0", optional = true }
 completest-nu = { version = "0.4.0", optional = true }
+write-json = { version = "0.1.4", optional = true }
 
 [dev-dependencies]
 snapbox = { version = "0.6.0", features = ["diff", "examples", "dir"] }
 clap = { path = "../", version = "4.0.0", default-features = false, features = ["std", "help"] }
 
 [features]
 default = []
+unstable-dynamic = ["clap_complete/unstable-dynamic", "dep:write-json"]
 unstable-shell-tests = ["dep:completest", "dep:completest-nu"]
 
 [lints]

clap_complete_nushell/Cargo.toml

@@ -0,0 +1,130 @@
+//! Implements dynamic completion for Nushell.
+//!
+//! There is no direct equivalent of other shells' `source $(COMPLETE=... your-clap-bin)` in nushell,
+//! because code being sourced must exist at parse-time.
+//!
+//! One way to get close to that is to split the completion integration into two parts:
+//!   1. a minimal part that goes into `env.nu`, which updates the actual completion integration
+//!   2. the completion integration, which is placed into the user's autoload directory
+//!
+//! To install the completion integration, the user runs
+//! ```nu
+//! COMPLETE=nushell your-clap-bin | save --raw --force --append $nu.env-path
+//! ```
+
+use clap::Command;
+use clap_complete::env::EnvCompleter;
+use std::ffi::{OsStr, OsString};
+use std::fmt::Display;
+use std::io::{Error, Write};
+use std::path::Path;
+
+struct ModeVar<'a>(&'a str);
+impl<'a> Display for ModeVar<'a> {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        write!(f, "_{0}__mode", self.0)
+    }
+}
+
+fn write_refresh_completion_integration(
+    var: &str,
+    name: &str,
+    completer: &str,
+    buf: &mut dyn Write,
+) -> Result<(), Error> {
+    let mode = ModeVar(var);
+    writeln!(
+        buf,
+        r#"
+# Refresh completer integration for {name} (must be in env.nu)
+do {{
+  # Search for existing script to avoid duplicates in case autoload dirs change
+  let completer_script_name = '{name}-completer.nu'
+  let autoload_dir = $nu.user-autoload-dirs
+    | where {{ path join $completer_script_name | path exists }}
+    | get 0 --optional
+    | default ($nu.user-autoload-dirs | get 0 --optional)
+  mkdir $autoload_dir
+
+  let completer_path = ($autoload_dir | path join $completer_script_name)
+  {var}=nushell {mode}=integration ^r#'{completer}'# | save --raw --force $completer_path
+}}
+        "#
+    )
+}
+
+fn write_completion_script(
+    var: &str,
+    name: &str,
+    _bin: &str,
+    completer: &str,
+    buf: &mut dyn Write,
+) -> Result<(), Error> {
+    writeln!(
+        buf,
+        r#"
+# Performs the completion for {name}
+def {name}-completer [
+    spans: list<string> # The spans that were passed to the external completer closure
+]: nothing -> list {{
+    {var}=nushell ^r#'{completer}'# -- ...$spans | from json
+}}
+
+@complete {name}-completer
+def --wrapped {name} [...args] {{
+  ^r#'{completer}'# ...$args
+}}
+"#
+    )
+}
+
+impl EnvCompleter for super::Nushell {
+    fn name(&self) -> &'static str {
+        "nushell"
+    }
+
+    fn is(&self, name: &str) -> bool {
+        name.eq_ignore_ascii_case("nushell") || name.eq_ignore_ascii_case("nu")
+    }
+
+    fn write_registration(
+        &self,
+        var: &str,
+        name: &str,
+        bin: &str,
+        completer: &str,
+        buf: &mut dyn Write,
+    ) -> Result<(), Error> {
+        let mode_var = format!("{}", ModeVar(var));
+        if std::env::var_os(&mode_var).as_ref().map(|x| x.as_os_str())
+            == Some(OsStr::new("integration"))
+        {
+            write_completion_script(var, name, bin, completer, buf)
+        } else {
+            write_refresh_completion_integration(var, name, completer, buf)
+        }
+    }
+
+    fn write_complete(
+        &self,
+        cmd: &mut Command,
+        args: Vec<OsString>,
+        current_dir: Option<&Path>,
+        buf: &mut dyn Write,
+    ) -> Result<(), Error> {
+        let idx = (args.len() - 1).max(0);
+        let candidates = clap_complete::engine::complete(cmd, args, idx, current_dir)?;
+        let mut strbuf = String::new();
+        {
+            let mut records = write_json::array(&mut strbuf);
+            for candidate in candidates {
+                let mut record = records.object();
+                record.string("value", candidate.get_value().to_string_lossy().as_ref());
+                if let Some(help) = candidate.get_help() {
+                    record.string("description", &help.to_string()[..]);
+                }
+            }
+        }
+        write!(buf, "{strbuf}")
+    }
+}

clap_complete_nushell/src/dynamic.rs

@@ -28,8 +28,12 @@ use clap::{builder::PossibleValue, Arg, ArgAction, Command};
 use clap_complete::Generator;
 
 /// Generate Nushell complete file
+#[derive(Copy, Clone, PartialEq, Eq, Debug)]
 pub struct Nushell;
 
+#[cfg(feature = "unstable-dynamic")]
+mod dynamic;
+
 impl Generator for Nushell {
     fn file_name(&self, name: &str) -> String {
         format!("{name}.nu")