feat(complete): Add dynamic completion for nushell

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

Nushell currently doesn't have a good story for adding what nushell
calls "external completers" in a modular fashion. Users can define
a single, global external completer. If they wish to combine multiple
external completers, they have to manually write a sort of 
meta-completer that dispatches to the individual completers based
on the first argument (the binary).

This PR generates a nushell module that offers three commands:
 - `complete`, which performs the actual completion
 - `handles`, which asks the module whether it is the correct 
    completer for a particular command line
 - `install`, which globally registers a completer that falls back
    to whatever completer was previously installed if `handles`
    rejects completing a command line.

The idea is that user's who already have a custom external completer
can integrate the generated module's `handles` and `complete` commands
into their completer.

Everyone else just puts
```nushell
use my-app-completer.nu
my-app-completer install
```
into their nushell config.

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,151 @@
+//! 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#"
+# Determines whether the completer for {name} is supposed to handle the command line
+def handles [
+    spans: list # The spans that were passed to the external completer closure
+]: nothing -> bool {{
+    ($spans | get --optional 0) == r#'{bin}'#
+}}
+
+# Performs the completion for {name}
+def complete [
+    spans: list # The spans that were passed to the external completer closure
+]: nothing -> list {{
+    {var}=nushell ^r#'{completer}'# -- ...$spans | from json
+}}
+
+# Installs this module as an external completer for {name} globally.
+#
+# For commands other {name}, it will fall back to whatever external completer
+# was defined previously (if any).
+$env.config = $env.config
+  | upsert completions.external.enable true
+  | upsert completions.external.completer {{ |original_config|
+      let previous_completer = $original_config
+        | get --optional completions.external.completer
+        | default {{ |spans| null }}
+      {{ |spans|
+        if (handles $spans) {{
+            complete $spans
+        }} else {{
+            do $previous_completer $spans
+        }}
+      }}
+  }}
+"#
+    )
+}
+
+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")