feat(cli): let -v mount managed volumes by name or id

docs/reference/cli/README.md

@@ -661,6 +661,7 @@ Used by `run` and `create` (defined at `src/cli/src/cli.rs:407-578`).
 | Flag | Short | Description |
 |------|-------|-------------|
 | `--volume VOLUME` | `-v` | Mount a volume; repeatable (see [Volume Mount Syntax](#volume-mount-syntax)) |
+| `--mount MOUNT` | — | Mount a managed volume by id (e.g. `src=volume://vol_123,target=/data`); REST runtime only |
 
 ### `ManagementFlags`
 
@@ -678,10 +679,11 @@ Used by `run` and `create` (defined at `src/cli/src/cli.rs:584-604`).
 
 ## Volume Mount Syntax
 
-`-v`/`--volume` accepts the grammar implemented at `src/cli/src/cli.rs:442-519`:
+`-v`/`--volume` accepts the grammar implemented at `src/cli/src/cli.rs:820-901`:
 
 ```
-VOLUME := HOST_PATH ':' BOX_PATH [':' OPTIONS]          # bind mount
+VOLUME := VOLUME_NAME_OR_ID ':' BOX_PATH                # managed volume
+        | HOST_PATH ':' BOX_PATH [':' OPTIONS]           # bind mount
         | BOX_PATH [':' OPTIONS]                         # anonymous volume
 ```
 
@@ -692,9 +694,12 @@ VOLUME := HOST_PATH ':' BOX_PATH [':' OPTIONS]          # bind mount
 | `HOST_PATH:BOX_PATH` | `/host/data:/data` | Bind mount (host directory must exist) |
 | `HOST_PATH:BOX_PATH:OPTIONS` | `/host/data:/data:ro` | Bind mount with options |
 | `C:\HOST\PATH:/BOX_PATH[:OPTIONS]` | `C:\data:/app/data:ro` | Windows drive paths are handled — the drive-letter colon is not treated as a separator |
+| `VOLUME_NAME_OR_ID:BOX_PATH` | `myvolume:/data` | Managed volume, resolved server-side by name or id (REST runtime only, see `has_managed_volumes` at `src/cli/src/cli.rs:1008-1014`); box path must be absolute and read-write |
 
 **Options:** `ro` (read-only) or `rw` (read-write, default). Other options are ignored. Relative host paths are canonicalized at parse time; missing host paths fail with `volume host path ...`.
 
+The host side is treated as a managed-volume name/id — instead of a local path — unless it looks like a filesystem path: a leading `/`, `.`, or `~`, an embedded `/` or `\`, or a Windows drive letter (`looks_like_host_path` at `src/cli/src/cli.rs:799-806`). A relative local bind mount must therefore use an explicit `./` prefix (e.g. `./cache:/data`); a bare `cache:/data` is read as a managed volume named `cache`.
+
 The anonymous-volume base directory is resolved as: `--home`, else `$BOXLITE_HOME`, else `~/.boxlite`, else the system temp dir.
 
 ---

src/cli/README.md

@@ -317,7 +317,7 @@ silently restarting it, because restarting would run the command a second time.
 | `--env KEY=VALUE` | `-e` | Set environment variables (repeatable) |
 | `--workdir PATH` | `-w` | Working directory in the box |
 | `--publish PORT` | `-p` | Publish a TCP box port locally (`80` = automatic host port, `8080:80` = fixed) |
-| `--volume VOLUME` | `-v` | Mount a volume (e.g. `hostPath:boxPath`, `boxPath` for anonymous) |
+| `--volume VOLUME` | `-v` | Mount a volume (e.g. `hostPath:boxPath`, `boxPath` for anonymous, `volumeNameOrId:boxPath` for a managed volume) |
 | `--cpus N` | | CPU limit |
 | `--memory MiB` | | Memory limit (MiB) |
 | `--cap-add CAPABILITY` | | Add a Linux capability (repeatable; accepts `CAP_` prefix or `ALL`) |
@@ -362,7 +362,7 @@ default, and `exec` still starts it on demand.
 | `--env KEY=VALUE` | `-e` | Environment variables |
 | `--workdir PATH` | `-w` | Working directory |
 | `--publish PORT` | `-p` | Publish a TCP box port locally (`80` = automatic host port, `8080:80` = fixed) |
-| `--volume VOLUME` | `-v` | Mount a volume (e.g. `hostPath:boxPath`, or box path for anonymous) |
+| `--volume VOLUME` | `-v` | Mount a volume (e.g. `hostPath:boxPath`, box path for anonymous, or `volumeNameOrId:boxPath` for a managed volume) |
 | `--cpus N` | | CPU limit |
 | `--memory MiB` | | Memory limit (MiB) |
 | `--cap-add CAPABILITY` | | Add a Linux capability (repeatable; accepts `CAP_` prefix or `ALL`) |

src/cli/src/cli.rs

@@ -750,11 +750,19 @@ struct ParsedVolumeSpec {
     host_path: Option<String>,
     guest_path: String,
     read_only: bool,
+    /// True when `host_path` names a managed volume (a bare name/id, resolved
+    /// server-side) rather than a local filesystem path to bind-mount.
+    is_managed: bool,
 }
 
 #[derive(Args, Debug, Clone)]
 pub struct VolumeFlags {
-    /// Mount a volume (format: hostPath:boxPath[:options], or boxPath for anonymous volume, e.g. /data:/app/data, /data:ro)
+    /// Mount a volume. `hostPath:boxPath[:options]` for a local bind mount
+    /// (e.g. `/data:/app/data`, `/data:/app/data:ro`); `boxPath` (or
+    /// `boxPath:ro`) for an anonymous local volume; a bare
+    /// `volumeNameOrId:boxPath` (no leading `/`, `.`, or `~`, e.g.
+    /// `myvolume:/data`) for a managed volume, resolved server-side and only
+    /// meaningful against a REST runtime.
     #[arg(short = 'v', long = "volume", value_name = "VOLUME")]
     pub volume: Vec<String>,
 
@@ -779,6 +787,24 @@ fn is_windows_absolute_path(path: &str) -> bool {
     b.len() >= 3 && b[0].is_ascii_alphabetic() && b[1] == b':' && (b[2] == b'\\' || b[2] == b'/')
 }
 
+/// True if the host side of a `-v` spec looks like a filesystem path rather
+/// than a managed-volume name/id. Mirrors Docker's own `-v` disambiguation
+/// (`docker run -v myvolume:/data` names a volume; only a leading `/`, `.`,
+/// `~`, an embedded `/` or `\`, or a Windows drive make it a bind-mount
+/// path) — a bare token is always a volume reference, never an implicit
+/// relative path. `\` counts as a separator regardless of host OS (like
+/// `is_windows_absolute_path` below, this recognizes Windows path syntax as
+/// a string pattern, not by asking the local filesystem), so a Windows
+/// relative path such as `subdir\cache:/guest` is still a bind mount.
+fn looks_like_host_path(host: &str) -> bool {
+    host.starts_with('/')
+        || host.starts_with('.')
+        || host.starts_with('~')
+        || host.contains('/')
+        || host.contains('\\')
+        || is_windows_absolute_path(host)
+}
+
 /// Parse options string (e.g. "ro" or "rw,nocopy") and return read_only. Other options are ignored.
 fn parse_volume_read_only(opts: &str) -> bool {
     opts.split(',').any(|o| o.trim().eq_ignore_ascii_case("ro"))
@@ -863,10 +889,14 @@ fn parse_volume_spec(s: &str) -> anyhow::Result<ParsedVolumeSpec> {
     if guest_path.is_empty() {
         anyhow::bail!("volume box path must be non-empty");
     }
+    let is_managed = host_path
+        .as_deref()
+        .is_some_and(|host| !looks_like_host_path(host));
     Ok(ParsedVolumeSpec {
         host_path,
         guest_path,
         read_only,
+        is_managed,
     })
 }
 
@@ -897,12 +927,30 @@ impl VolumeFlags {
         let base = anonymous_volume_base(home);
         for s in self.volume.iter() {
             let spec = parse_volume_spec(s)?;
-            let host_path = match spec.host_path {
-                // TODO(#942): when the host side of a `-v <src>:<guest>` spec is a
-                // bare name (not a path) that matches a named volume, resolve it
-                // to the volume's mountpoint here (via the volume backend) and
-                // bind that payload dir instead of treating the name as a literal
-                // host path.
+            let ParsedVolumeSpec {
+                host_path,
+                guest_path,
+                read_only,
+                is_managed,
+            } = spec;
+            let host_path = match host_path {
+                Some(host) if is_managed => {
+                    // Managed volume reference: resolved server-side (REST
+                    // create/attach already accept id-or-name, scoped to the
+                    // caller's org), so — unlike a bind-mount path — this
+                    // string is never touched on this host.
+                    if guest_path.is_empty() || !guest_path.starts_with('/') {
+                        anyhow::bail!(
+                            "managed volume box path must be absolute (e.g. {host}:/data)"
+                        );
+                    }
+                    if read_only {
+                        anyhow::bail!(
+                            "managed volume mounts are read-write only for now (remove :ro from {s:?})"
+                        );
+                    }
+                    host
+                }
                 Some(host) => {
                     let mut path = host;
                     if std::path::Path::new(&path).is_relative() && !is_windows_absolute_path(&path)
@@ -926,8 +974,8 @@ impl VolumeFlags {
             };
             opts.volumes.push(VolumeSpec {
                 host_path,
-                guest_path: spec.guest_path,
-                read_only: spec.read_only,
+                guest_path,
+                read_only,
             });
         }
         Ok(())
@@ -953,8 +1001,16 @@ impl VolumeFlags {
         Ok(())
     }
 
+    /// True if any `-v` or `--mount` entry is a managed-volume reference
+    /// rather than a local bind mount — these require a REST runtime.
+    /// Unparseable `-v` entries are treated as non-managed here; `apply_to`
+    /// surfaces the real parse error when it runs moments later.
     pub fn has_managed_volumes(&self) -> bool {
         !self.mount.is_empty()
+            || self
+                .volume
+                .iter()
+                .any(|s| parse_volume_spec(s).is_ok_and(|spec| spec.is_managed))
     }
 }
 
@@ -1901,6 +1957,126 @@ mod tests {
         assert!(args.volume.volume.is_empty());
     }
 
+    // --- Managed volumes via -v (bare name/id), alongside --mount ---
+
+    #[test]
+    fn test_parse_volume_spec_bare_name_is_managed() {
+        let spec = super::parse_volume_spec("myvolume:/data").unwrap();
+        assert_eq!(spec.host_path.as_deref(), Some("myvolume"));
+        assert_eq!(spec.guest_path, "/data");
+        assert!(spec.is_managed);
+    }
+
+    #[test]
+    fn test_parse_volume_spec_local_paths_are_not_managed() {
+        assert!(!super::parse_volume_spec("/host:/guest").unwrap().is_managed);
+        assert!(
+            !super::parse_volume_spec("./host:/guest")
+                .unwrap()
+                .is_managed
+        );
+        assert!(
+            !super::parse_volume_spec("~/host:/guest")
+                .unwrap()
+                .is_managed
+        );
+        assert!(
+            !super::parse_volume_spec("sub/dir:/guest")
+                .unwrap()
+                .is_managed
+        );
+        assert!(
+            !super::parse_volume_spec(r"C:\data:/guest")
+                .unwrap()
+                .is_managed
+        );
+        // Windows-relative, no leading `.` or drive letter: `\` still counts
+        // as a path separator, so this must not be misread as a managed
+        // volume named `subdir\cache`.
+        assert!(
+            !super::parse_volume_spec(r"subdir\cache:/guest")
+                .unwrap()
+                .is_managed
+        );
+    }
+
+    #[test]
+    fn test_volume_flags_apply_to_managed_volume() {
+        let flags = VolumeFlags {
+            volume: vec!["myvolume:/data".to_string()],
+            mount: vec![],
+        };
+        let mut opts = BoxOptions::default();
+        flags.apply_to(&mut opts, None).unwrap();
+
+        assert_eq!(opts.volumes.len(), 1);
+        // Passed through verbatim: never canonicalized against this host's
+        // filesystem, unlike a bind-mount path.
+        assert_eq!(opts.volumes[0].host_path, "myvolume");
+        assert_eq!(opts.volumes[0].guest_path, "/data");
+        assert!(!opts.volumes[0].read_only);
+    }
+
+    #[test]
+    fn test_volume_flags_apply_to_managed_volume_rejects_relative_box_path() {
+        let flags = VolumeFlags {
+            volume: vec!["myvolume:data".to_string()],
+            mount: vec![],
+        };
+        let mut opts = BoxOptions::default();
+        let err = flags
+            .apply_to(&mut opts, None)
+            .expect_err("managed volume box path must be absolute");
+
+        assert!(
+            err.to_string().contains("box path must be absolute"),
+            "unexpected error: {err}"
+        );
+    }
+
+    #[test]
+    fn test_volume_flags_apply_to_managed_volume_rejects_read_only() {
+        let flags = VolumeFlags {
+            volume: vec!["myvolume:/data:ro".to_string()],
+            mount: vec![],
+        };
+        let mut opts = BoxOptions::default();
+        let err = flags
+            .apply_to(&mut opts, None)
+            .expect_err("managed volume mounts are read-write only for now");
+
+        assert!(
+            err.to_string().contains("read-write only"),
+            "unexpected error: {err}"
+        );
+    }
+
+    #[test]
+    fn test_volume_flags_has_managed_volumes_via_dash_v() {
+        let managed = VolumeFlags {
+            volume: vec!["myvolume:/data".to_string()],
+            mount: vec![],
+        };
+        assert!(managed.has_managed_volumes());
+
+        let local = VolumeFlags {
+            volume: vec!["/host:/data".to_string()],
+            mount: vec![],
+        };
+        assert!(!local.has_managed_volumes());
+    }
+
+    #[test]
+    fn test_run_parses_managed_volume_via_dash_v() {
+        let cli = Cli::try_parse_from(["boxlite", "run", "-v", "myvolume:/data", "alpine"])
+            .expect("run -v myvolume:/data should parse");
+        let Commands::Run(args) = cli.command else {
+            panic!("expected run command");
+        };
+
+        assert_eq!(args.volume.volume, vec!["myvolume:/data"]);
+    }
+
     // ─── auth subcommand parse tests ───────────────────────────────────────
 
     use crate::commands::{auth::AuthCommand, network::NetworkCommand};