feat(cli): add deno watch subcommand (#35301)

Adds a `deno watch <file>` subcommand that aliases
`deno run --watch-hmr <file>`. Watch-with-hot-module-replacement is one
of the more useful development workflows, but it was only reachable through
a long flag on `deno run`. A dedicated subcommand makes it short to type
and discoverable from `deno --help`.

Internally `watch` reuses the existing `run` argument set and parsing
path, only defaulting the watch configuration to HMR when no explicit watch
flag is given, so all `run` flags (including `--watch-hmr=<path>`,
`--watch-exclude`, and `--no-clear-screen`) continue to work and the
behavior stays identical to `deno run --watch-hmr`.

Author: bartlomieju

cli/args/flags.rs

@@ -956,6 +956,8 @@ static DENO_HELP: &str = cstr!(
                   <p(245)>deno run main.ts  |  deno run --allow-net=google.com main.ts  |  deno main.ts</>
     <g>serve</>        Run a server
                   <p(245)>deno serve main.ts</>
+    <g>watch</>        Run a program, watching for changes and hot-replacing modules
+                  <p(245)>deno watch main.ts</>
     <g>task</>         Run a task defined in the configuration file
                   <p(245)>deno task dev</>
     <g>repl</>         Start an interactive Read-Eval-Print Loop (REPL) for Deno
@@ -1303,7 +1305,8 @@ pub fn flags_from_vec_with_initial_cwd(
         "lsp" => lsp_parse(&mut flags, &mut m),
         "outdated" => outdated_parse(&mut flags, &mut m, false)?,
         "repl" => repl_parse(&mut flags, &mut m)?,
-        "run" => run_parse(&mut flags, &mut m, app, false)?,
+        "run" => run_parse(&mut flags, &mut m, app, false, false)?,
+        "watch" => run_parse(&mut flags, &mut m, app, false, true)?,
         "serve" => serve_parse(&mut flags, &mut m, app)?,
         "task" => task_parse(&mut flags, &mut m, app)?,
         "test" => test_parse(&mut flags, &mut m)?,
@@ -1334,7 +1337,7 @@ pub fn flags_from_vec_with_initial_cwd(
         });
 
       if has_non_globals || matches.contains_id("script_arg") {
-        run_parse(&mut flags, &mut matches, app, true)?;
+        run_parse(&mut flags, &mut matches, app, true, false)?;
       } else {
         handle_repl_flags(
           &mut flags,
@@ -1548,6 +1551,7 @@ pub fn clap_root() -> Command {
         .global(true),
     )
     .subcommand(run_subcommand())
+    .subcommand(watch_subcommand())
     .subcommand(serve_subcommand())
     .defer(|cmd| {
       let cmd = cmd
@@ -4083,6 +4087,18 @@ Specifying the filename '-' to read the file from stdin.
 <y>Read more:</> <c>https://docs.deno.com/go/run</>"), UnstableArgsConfig::ResolutionAndRuntime), false)
 }
 
+fn watch_subcommand() -> Command {
+  run_args(command("watch", cstr!("Run a JavaScript or TypeScript program, watching for file changes and hot-replacing modules.
+
+This is an alias for <c>deno run --watch-hmr</>. The process restarts if hot replacement fails.
+  <p(245)>deno watch main.ts</>
+
+Local files from the entry point module graph are watched by default. Additional paths can be passed with <c>--watch-hmr</>:
+  <p(245)>deno watch --watch-hmr=./templates main.ts</>
+
+<y>Read more:</> <c>https://docs.deno.com/go/run</>"), UnstableArgsConfig::ResolutionAndRuntime), false)
+}
+
 fn serve_host_validator(host: &str) -> Result<String, String> {
   if Url::parse(&format!("internal://{host}:9999")).is_ok() {
     Ok(host.to_owned())
@@ -7725,6 +7741,7 @@ fn run_parse(
   matches: &mut ArgMatches,
   app: Command,
   bare: bool,
+  force_hmr: bool,
 ) -> clap::error::Result<()> {
   runtime_args_parse(flags, matches, true, true, true)?;
   ext_arg_parse(flags, matches);
@@ -7748,7 +7765,30 @@ fn run_parse(
     Some(mut script_arg) => {
       let script = script_arg.next().unwrap();
       flags.argv.extend(script_arg);
-      let watch = watch_arg_parse_with_paths(matches)?;
+      let mut watch = watch_arg_parse_with_paths(matches)?;
+      // `deno watch` is an alias for `deno run --watch-hmr`, so enable hot
+      // module replacement watching by default when no explicit watch flag was
+      // passed.
+      if force_hmr {
+        match &mut watch {
+          Some(watch) => watch.hmr = true,
+          None => {
+            watch = Some(WatchFlagsWithPaths {
+              hmr: true,
+              paths: vec![],
+              no_clear_screen: matches.get_flag("no-clear-screen"),
+              exclude: matches
+                .remove_many::<String>("watch-exclude")
+                .map(|f| {
+                  f.flat_map(flat_escape_split_commas)
+                    .collect::<Result<_, _>>()
+                })
+                .transpose()?
+                .unwrap_or_default(),
+            });
+          }
+        }
+      }
       if script == "-" && watch.is_some() {
         return Err(clap::Error::raw(
           clap::error::ErrorKind::ArgumentConflict,
@@ -9186,6 +9226,94 @@ mod tests {
     assert!(r.is_err());
   }
 
+  #[test]
+  fn watch_subcommand() {
+    // `deno watch script.ts` is an alias for `deno run --watch-hmr script.ts`.
+    let r = flags_from_vec(svec!["deno", "watch", "script.ts"]);
+    let flags = r.unwrap();
+    assert_eq!(
+      flags,
+      Flags {
+        subcommand: DenoSubcommand::Run(RunFlags {
+          script: "script.ts".to_string(),
+          watch: Some(WatchFlagsWithPaths {
+            hmr: true,
+            paths: vec![],
+            no_clear_screen: false,
+            exclude: vec![],
+          }),
+          bare: false,
+          coverage_dir: None,
+          print_task_list: false,
+        }),
+        code_cache_enabled: true,
+        ..Flags::default()
+      }
+    );
+
+    // Additional watched paths and watch options are still respected.
+    let r = flags_from_vec(svec![
+      "deno",
+      "watch",
+      "--watch-hmr=foo.txt",
+      "--no-clear-screen",
+      "--watch-exclude=bar.txt",
+      "script.ts"
+    ]);
+    let flags = r.unwrap();
+    assert_eq!(
+      flags,
+      Flags {
+        subcommand: DenoSubcommand::Run(RunFlags {
+          script: "script.ts".to_string(),
+          watch: Some(WatchFlagsWithPaths {
+            hmr: true,
+            paths: vec![String::from("foo.txt")],
+            no_clear_screen: true,
+            exclude: vec![String::from("bar.txt")],
+          }),
+          bare: false,
+          coverage_dir: None,
+          print_task_list: false,
+        }),
+        code_cache_enabled: true,
+        ..Flags::default()
+      }
+    );
+
+    // `--watch-exclude` is honored even without an explicit `--watch-hmr` flag.
+    let r = flags_from_vec(svec![
+      "deno",
+      "watch",
+      "--watch-exclude=bar.txt",
+      "script.ts"
+    ]);
+    let flags = r.unwrap();
+    assert_eq!(
+      flags,
+      Flags {
+        subcommand: DenoSubcommand::Run(RunFlags {
+          script: "script.ts".to_string(),
+          watch: Some(WatchFlagsWithPaths {
+            hmr: true,
+            paths: vec![],
+            no_clear_screen: false,
+            exclude: vec![String::from("bar.txt")],
+          }),
+          bare: false,
+          coverage_dir: None,
+          print_task_list: false,
+        }),
+        code_cache_enabled: true,
+        ..Flags::default()
+      }
+    );
+
+    // Reading from stdin while watching is not supported.
+    let r = flags_from_vec(svec!["deno", "watch", "-"]);
+    assert!(r.is_err());
+  }
+
   #[test]
   fn run_watch_with_external() {
     let r = flags_from_vec(svec!["deno", "--watch=file1,file2", "script.ts"]);

tests/specs/watch/__test__.jsonc

@@ -0,0 +1,17 @@
+{
+  "tests": {
+    // `deno watch` is an alias for `deno run --watch-hmr`, so its help text
+    // points at the same behavior.
+    "help": {
+      "args": "watch --help",
+      "output": "help.out"
+    },
+    // Watching while reading the program from stdin is not supported, same as
+    // `deno run --watch-hmr -`.
+    "stdin_conflict": {
+      "args": "watch -",
+      "exitCode": 1,
+      "output": "stdin_conflict.out"
+    }
+  }
+}

tests/specs/watch/help.out

@@ -0,0 +1,7 @@
+Run a JavaScript or TypeScript program, watching for file changes and hot-replacing modules.
+
+This is an alias for deno run --watch-hmr. The process restarts if hot replacement fails.
+  deno watch main.ts
+[WILDCARD]
+Usage: deno watch [OPTIONS] [SCRIPT_ARG]...
+[WILDCARD]

tests/specs/watch/stdin_conflict.out

@@ -0,0 +1,2 @@
+error: --watch and --watch-hmr cannot be used while reading from stdin.
+[WILDCARD]