feat: support external subcommands via PATH (#1343) (#2278)

## **Summary**

This PR adds support for external subcommands in the `hugr-cli`binary,
as per the feature request from issue #1343.
Now when you run:

```bash
hugr <subcommand> [args…]
```

if an executable named `hugr-<subcommand>` is on your `PATH`, it will be
called with the same `[args…]`. If the binary is missing or fails, you
get a clear error and non-zero exit code.

---

## **Details**

**Functionality:**

* **`src/main.rs`**

  1. Checks for no subcommand and errors out.
  2. Builds `hugr-<subcommand>` from the first arg.
  3. Runs it with `std::process::Command`, passing the remaining args.
  4. On error:

     * If not found →

       ```
       error: no such subcommand: '<subcommand>'.  
       Could not find 'hugr-<subcommand>' in PATH.
       ```
     * Other I/O errors →

       ```
       error: failed to invoke '<executable>': <error>
       ```
**Testing:**

* **`hugr-cli/tests/external.rs`**

  * **`test_missing_external_command`**
    Runs `hugr idontexist` and checks for a “no such subcommand” error.
  * **`test_external_command_invocation`**

1. Creates a temp dir with a dummy `hugr-dummy` script that echoes its
args and exits `42`.
    2. Prepends that dir to `PATH`.
3. Runs `hugr dummy foo bar` and checks it prints `dummy called: foo
bar` and exits `42`.
* Adds `tempfile` to `dev-dependencies` in `Cargo.toml` for these tests.

---

Closes #1343

---------

Co-authored-by: Agustín Borgna <121866228+aborgna-q@users.noreply.github.com>

Author: OsamaMIT

Cargo.lock

@@ -70,6 +70,7 @@ serde_yaml = "0.9.34"
 smol_str = "0.3.1"
 static_assertions = "1.1.0"
 strum = "0.27.0"
+tempfile = "3.20"
 thiserror = "2.0.12"
 typetag = "0.2.20"
 clap = { version = "4.5.38" }

Cargo.toml

@@ -37,6 +37,7 @@ struct_missing = "warn"
 assert_cmd = { workspace = true }
 assert_fs = { workspace = true }
 predicates = { workspace = true }
+tempfile = { workspace = true }
 rstest.workspace = true
 
 [[bin]]

hugr-cli/Cargo.toml

@@ -11,12 +11,35 @@ fn main() {
         CliArgs::Validate(args) => run_validate(args),
         CliArgs::GenExtensions(args) => args.run_dump(&hugr::std_extensions::STD_REG),
         CliArgs::Mermaid(args) => run_mermaid(args),
-        CliArgs::External(_) => {
-            // TODO: Implement support for external commands.
-            // Running `hugr COMMAND` would look for `hugr-COMMAND` in the path
-            // and run it.
-            eprintln!("External commands are not supported yet.");
-            std::process::exit(1);
+        CliArgs::External(args) => {
+            // External subcommand support: invoke `hugr-<subcommand>`
+            if args.is_empty() {
+                eprintln!("No external subcommand specified.");
+                std::process::exit(1);
+            }
+            let subcmd = args[0].to_string_lossy();
+            let exe = format!("hugr-{}", subcmd);
+            let rest: Vec<_> = args[1..]
+                .iter()
+                .map(|s| s.to_string_lossy().to_string())
+                .collect();
+            match std::process::Command::new(&exe).args(&rest).status() {
+                Ok(status) => {
+                    if !status.success() {
+                        std::process::exit(status.code().unwrap_or(1));
+                    }
+                }
+                Err(e) if e.kind() == std::io::ErrorKind::NotFound => {
+                    eprintln!(
+                        "error: no such subcommand: '{subcmd}'.\nCould not find '{exe}' in PATH."
+                    );
+                    std::process::exit(1);
+                }
+                Err(e) => {
+                    eprintln!("error: failed to invoke '{exe}': {e}");
+                    std::process::exit(1);
+                }
+            }
         }
         _ => {
             eprintln!("Unknown command");

hugr-cli/src/main.rs

@@ -0,0 +1,45 @@
+//! Tests for external subcommand support in hugr-cli.
+#![cfg(all(test, not(miri)))]
+
+use assert_cmd::Command;
+use predicates::str::contains;
+use std::env;
+use std::fs;
+#[cfg(unix)]
+use std::os::unix::fs::PermissionsExt;
+use tempfile::TempDir;
+
+#[test]
+fn test_missing_external_command() {
+    let mut cmd = Command::cargo_bin("hugr").unwrap();
+    cmd.arg("idontexist");
+    cmd.assert()
+        .failure()
+        .stderr(contains("no such subcommand"));
+}
+
+#[test]
+#[cfg_attr(not(unix), ignore = "Dummy program supported on Unix-like systems")]
+fn test_external_command_invocation() {
+    // Create a dummy external command in a temp dir
+    let tempdir = TempDir::new().unwrap();
+    let bin_path = tempdir.path().join("hugr-dummy");
+    fs::write(&bin_path, b"#!/bin/sh\necho dummy called: $@\nexit 42\n").unwrap();
+    let mut perms = fs::metadata(&bin_path).unwrap().permissions();
+    #[cfg(unix)]
+    perms.set_mode(0o755);
+    fs::set_permissions(&bin_path, perms).unwrap();
+
+    // Prepend tempdir to PATH
+    let orig_path = env::var("PATH").unwrap();
+    let new_path = format!("{}:{}", tempdir.path().display(), orig_path);
+    let mut cmd = Command::cargo_bin("hugr").unwrap();
+    cmd.env("PATH", new_path);
+    cmd.arg("dummy");
+    cmd.arg("foo");
+    cmd.arg("bar");
+    cmd.assert()
+        .failure()
+        .stdout(contains("dummy called: foo bar"))
+        .code(42);
+}

hugr-cli/tests/external.rs

@@ -69,7 +69,10 @@ fn test_doesnt_exist(mut val_cmd: Command) {
     val_cmd
         .assert()
         .failure()
-        .stderr(contains("No such file or directory"));
+        // clap now prints something like:
+        //   error: Invalid value for [INPUT]: Could not open "foobar": (os error 2)
+        // so just look for "Could not open"
+        .stderr(contains("Could not open"));
 }
 
 #[rstest]