feat(spec): allow a mount at the top level

docs/spec/reference/cmd.md

@@ -83,6 +83,23 @@ task commands as if they were statically defined in the usage spec.
 a shebang script therefore needs a POSIX shell to be available; one that invokes a program
 directly, like `mycli mount-usage-tasks` above, works either way.
 
+### Mounting at the top level
+
+A `mount` also works as a top-level node, for a CLI whose _own_ commands are
+discovered rather than declared — one whose subcommands come from plugins, say:
+
+```kdl
+name "mycli"
+bin "mycli"
+cmd "install"
+mount run="mycli plugin-commands"
+```
+
+The root's mount runs only when a _word_ matches nothing already declared, so
+`mycli install` costs nothing extra and only `mycli something-from-a-plugin` pays
+for discovery. Flags never trigger it — `mycli --help` does not run your mount
+command — so declaring the commands you know about keeps the common path free.
+
 ### Global flags and mounted commands
 
 A mounted command describes a different program, so the flags of the commands it is mounted under

lib/src/parse.rs

@@ -592,8 +592,31 @@ fn parse_partial_with_env(
     // Track whether we've already applied the default_subcommand to prevent
     // multiple switches (e.g., if default is "run" and there's a task named "run")
     let mut used_default_subcommand = false;
+    // Whether the command in scope has had its own mounts run. A mount on the root
+    // is the case that needs this: a subcommand's mounts are run when the parser
+    // descends into it, but nothing descends into the root.
+    let mut mounts_resolved = false;
 
     while idx < input.len() {
+        // Only for a word that could name a command, and only when it matches
+        // nothing already declared. A CLI that declares its commands and mounts more
+        // does not spawn a process for every invocation, and a flag — `--help`, or
+        // anything unrecognized — never triggers discovery at all, which it would
+        // otherwise do simply by not being a subcommand.
+        if !mounts_resolved
+            && !out.cmd.mounts.is_empty()
+            && !input[idx].starts_with('-')
+            && out.cmd.find_subcommand(&input[idx]).is_none()
+        {
+            mounts_resolved = true;
+            let mut mounted = out.cmd.clone();
+            mounted.mount(&mount_prefix_words(&prefix_flags))?;
+            merge_subcommand_flags(&mut out.available_flags, gather_flags(&mounted), false);
+            if let Some(last) = out.cmds.last_mut() {
+                *last = mounted.clone();
+            }
+            out.cmd = mounted;
+        }
         if let Some(subcommand) = out.cmd.find_subcommand(&input[idx]) {
             let mut subcommand = subcommand.clone();
             // Pass prefix words (global flags before this subcommand) to mount
@@ -610,6 +633,8 @@ fn parse_partial_with_env(
             input.remove(idx);
             out.cmds.push(subcommand.clone());
             out.cmd = subcommand.clone();
+            // A descent already ran the new command's mounts, above.
+            mounts_resolved = true;
             prefix_flags.clear();
             // Continue from current position (don't reset to 0)
             // After remove(), idx now points to the next element
@@ -670,6 +695,9 @@ fn parse_partial_with_env(
                         out.cmds.push(subcommand.clone());
                         out.cmd = subcommand.clone();
                         prefix_flags.clear();
+                        // This descent ran the new command's mounts, so lazy
+                        // discovery must not run them a second time.
+                        mounts_resolved = true;
                         used_default_subcommand = true;
                         // Continue the loop to check if this word is a subcommand of the
                         // default subcommand (e.g., a task name added via mount).
@@ -1524,6 +1552,76 @@ arg "[input]"
         assert_eq!(first_string_value(&parsed), "input.txt");
     }
 
+    #[cfg(unix)]
+    #[test]
+    fn a_mount_on_the_root_discovers_subcommands() {
+        // The root is a command like any other, so it can find its own subcommands
+        // by running something. Uses `echo` rather than a fixture because resolving
+        // a mount is what is being tested.
+        let spec: Spec = r#"
+name "ex"
+bin "ex"
+cmd "declared"
+mount run="echo 'cmd \"discovered\"'"
+"#
+        .parse()
+        .unwrap();
+
+        let out = parse(&spec, &["ex".to_string(), "discovered".to_string()]).unwrap();
+        assert_eq!(out.cmd.name, "discovered");
+    }
+
+    #[cfg(unix)]
+    #[test]
+    fn a_flag_does_not_run_the_mount() {
+        // A flag matches no subcommand, which would have been enough to trigger
+        // discovery — so `ex --help` spawned a process. The mount fails if it runs,
+        // so parsing at all is the proof that it did not.
+        let spec: Spec = r#"
+name "ex"
+bin "ex"
+flag "--verbose"
+cmd "declared"
+mount run="exit 1"
+"#
+        .parse()
+        .unwrap();
+
+        let out = parse(&spec, &["ex".to_string(), "--verbose".to_string()]).unwrap();
+        assert_eq!(out.cmd.name, "ex");
+    }
+
+    #[cfg(unix)]
+    #[test]
+    fn a_declared_subcommand_does_not_run_the_mount() {
+        // The mount would fail if it ran, so this parsing at all is the proof that
+        // discovery is skipped when the word is already known. Worth pinning: a root
+        // mount that resolved eagerly would spawn a process on every invocation.
+        let spec: Spec = r#"
+name "ex"
+bin "ex"
+cmd "declared"
+mount run="exit 1"
+"#
+        .parse()
+        .unwrap();
+
+        let out = parse(&spec, &["ex".to_string(), "declared".to_string()]).unwrap();
+        assert_eq!(out.cmd.name, "declared");
+    }
+
+    #[test]
+    fn a_root_mount_survives_being_written_out() {
+        let spec: Spec = "name \"ex\"\nbin \"ex\"\nmount run=\"ex plugins --usage\"\n"
+            .parse()
+            .unwrap();
+        assert_eq!(spec.cmd.mounts.len(), 1);
+
+        let reparsed: Spec = spec.to_string().parse().unwrap();
+        assert_eq!(reparsed.cmd.mounts.len(), 1, "written:\n{spec}");
+        assert_eq!(reparsed.cmd.mounts[0].run, "ex plugins --usage");
+    }
+
     #[test]
     fn test_mount_prefix_applies_flag_overrides() {
         let stdin = Arc::new(

lib/src/spec/cmd.rs

@@ -424,6 +424,11 @@ impl SpecCommand {
         usage.trim().to_string()
     }
     pub(crate) fn merge(&mut self, other: Self) {
+        // Merging can add subcommands and aliases, and `find_subcommand` memoizes
+        // its lookup into a OnceLock — so the cache has to go, or a name that
+        // arrived here would not be findable. This worked before only because
+        // mounting happened to precede the first lookup on a given command.
+        self.subcommand_lookup = OnceLock::new();
         // Destructured exhaustively (no `..`) so that adding a field to
         // SpecCommand fails to compile until this decides what merging it means.
         // Runtime-derived fields are explicitly ignored rather than skipped.

lib/src/spec/mod.rs

@@ -204,6 +204,10 @@ impl Spec {
                 "usage" => schema.usage = node.arg(0)?.ensure_string()?,
                 "arg" => schema.cmd.args.push(SpecArg::parse(ctx, &node)?),
                 "flag" => schema.cmd.flags.push(SpecFlag::parse(ctx, &node)?),
+                // The root is a command like any other, so it can discover its own
+                // subcommands by running something. A CLI whose top-level commands
+                // come from plugins has no other way to say so.
+                "mount" => schema.cmd.mounts.push(crate::SpecMount::parse(ctx, &node)?),
                 "cmd" => {
                     let node: SpecCommand = SpecCommand::parse(ctx, &node)?;
                     schema.cmd.subcommands.insert(node.name.to_string(), node);
@@ -489,6 +493,11 @@ impl Display for Spec {
         for arg in self.cmd.args.iter() {
             nodes.push(arg.into());
         }
+        // Written here rather than by SpecCommand, because the root's own nodes
+        // live at the top level of the document instead of inside a `cmd` block.
+        for mount in self.cmd.mounts.iter() {
+            nodes.push(mount.into());
+        }
         for example in self.examples.iter() {
             nodes.push(example.into());
         }