feat!: add -w/--watch flag for file watching and hot reload

BREAKING CHANGE: Stdin mode (`-`) now requires the `-w` flag because
stdin is specifically for hot-reload scenarios (null-terminated scripts).
For one-shot stdin input, use `http-nu eval -` instead.

Before: `http-nu :3001 -`
After:  `http-nu :3001 - -w`

New features:
- File watch mode: `http-nu :3001 -w ./handler.nu` watches the script's
  directory for changes and hot-reloads on any file modification
- Uses `notify` crate for cross-platform file system watching
- 100ms debounce to coalesce rapid file system events
- Watches recursively, so changes to included files trigger reload too
- The `-w` flag is incompatible with `-c` (inline commands)

Author: cablehead

Cargo.lock

@@ -67,6 +67,8 @@ xxhash-rust = { version = "0.8.15", features = ["xxh3"] }
 syntect = "5.3.0"
 syntect-assets = "0.23.6"
 pulldown-cmark = "0.12.2"
+notify = "8"
+notify-debouncer-mini = "0.6"
 
 [build-dependencies]
 syntect = "5.3.0"

Cargo.toml

@@ -42,8 +42,8 @@
 - [Reference](#reference)
   - [GET: Hello world](#get-hello-world)
   - [UNIX domain sockets](#unix-domain-sockets)
-  - [Reading closures from stdin](#reading-closures-from-stdin)
-    - [Dynamic reloads](#dynamic-reloads)
+  - [Watch Mode](#watch-mode)
+    - [Reading scripts from stdin](#reading-scripts-from-stdin)
   - [POST: echo](#post-echo)
   - [Request metadata](#request-metadata)
   - [Response metadata](#response-metadata)
@@ -130,47 +130,33 @@ $ curl -s --unix-socket ./sock localhost
 Hello world
 ```
 
-### Reading scripts from stdin
+### Watch Mode
 
-Pass `-` to read the script from stdin:
+Use `-w` / `--watch` to automatically reload when files change:
 
 ```bash
-$ echo '{|req| "Hello from stdin"}' | http-nu :3001 -
-$ curl -s localhost:3001
-Hello from stdin
+$ http-nu :3001 -w ./handler.nu
 ```
 
-Or pipe a file:
-
-```bash
-$ cat handler.nu | http-nu :3001 -
-```
+This watches the script's directory for any changes (including included files)
+and hot-reloads the handler. Useful during development.
 
 Check out the [`examples/basic.nu`](examples/basic.nu) file in the repository
 for a complete example that implements a mini web server with multiple routes,
 form handling, and streaming responses.
 
-#### Dynamic reloads
+#### Reading scripts from stdin
 
-When reading from stdin, you can send multiple null-terminated scripts to
-hot-reload the handler without restarting the server. This example starts with
-"v1", then after 5 seconds switches to "v2":
+For programmatic control, pass `-` with `-w` to read null-terminated scripts
+from stdin. Each script hot-reloads the handler:
 
 ```bash
-$ (printf '{|req| "v1"}\0'; sleep 5; printf '{|req| "v2"}') | http-nu :3001 -
+$ (printf '{|req| "v1"}\0'; sleep 5; printf '{|req| "v2"}') | http-nu :3001 - -w
 ```
 
 JSON status is emitted to stdout: `"start"` on first load, `"reload"` on
 updates, `"error"` on parse failures.
 
-Watch a file and reload on changes:
-
-```nushell
-watch ./serve.nu | prepend {operation: Write} | each {
-  (cat serve.nu) + (char -i 0)
-} | to text | http-nu /run/sock -
-```
-
 ### POST: echo
 
 ```bash

README.md

@@ -22,6 +22,7 @@ use hyper::service::service_fn;
 use hyper_util::rt::{TokioExecutor, TokioIo};
 use hyper_util::server::conn::auto::Builder as HttpConnectionBuilder;
 use hyper_util::server::graceful::GracefulShutdown;
+use notify::{RecursiveMode, Watcher};
 use tokio::signal;
 use tokio::sync::mpsc;
 
@@ -48,9 +49,15 @@ struct Args {
     script: Option<String>,
 
     /// Run script from command line instead of file
-    #[clap(short = 'c', long = "commands")]
+    #[clap(short = 'c', long = "commands", conflicts_with = "watch")]
     commands: Option<String>,
 
+    /// Watch for script changes and reload automatically.
+    /// For file scripts: watches the script's directory for any changes.
+    /// For stdin (-): reads null-terminated scripts for hot reload.
+    #[clap(short = 'w', long = "watch")]
+    watch: bool,
+
     /// Log format: human (live-updating) or jsonl (structured)
     #[clap(long, default_value = "human")]
     log_format: LogFormat,
@@ -105,6 +112,66 @@ fn create_base_engine(
     Ok(engine)
 }
 
+/// Spawns a file watcher that watches the script's directory for any changes.
+/// When a change is detected, re-reads the script file and sends it.
+fn spawn_file_watcher(script_path: PathBuf, tx: mpsc::Sender<String>) {
+    std::thread::spawn(move || {
+        let watch_dir = script_path.parent().unwrap_or(&script_path).to_path_buf();
+
+        let (raw_tx, raw_rx) = std::sync::mpsc::channel();
+
+        let mut watcher = notify::recommended_watcher(raw_tx).expect("Failed to create watcher");
+
+        watcher
+            .watch(&watch_dir, RecursiveMode::Recursive)
+            .expect("Failed to watch directory");
+
+        // Keep watcher alive
+        let _watcher = watcher;
+
+        // Set to past time so first event isn't debounced
+        let mut last_reload = std::time::Instant::now() - Duration::from_secs(1);
+        let debounce = Duration::from_millis(100);
+
+        for result in raw_rx {
+            match result {
+                Ok(event) => {
+                    // Only react to modifications, not access/open events
+                    use notify::EventKind;
+                    let is_modification = matches!(
+                        event.kind,
+                        EventKind::Create(_) | EventKind::Modify(_) | EventKind::Remove(_)
+                    );
+                    if !is_modification {
+                        continue;
+                    }
+
+                    // Debounce rapid events
+                    if last_reload.elapsed() < debounce {
+                        continue;
+                    }
+                    last_reload = std::time::Instant::now();
+
+                    // Re-read and send the script file
+                    match std::fs::read_to_string(&script_path) {
+                        Ok(content) => {
+                            if tx.blocking_send(content).is_err() {
+                                break;
+                            }
+                        }
+                        Err(e) => {
+                            eprintln!("Error reading script file: {e}");
+                        }
+                    }
+                }
+                Err(e) => {
+                    eprintln!("Watch error: {e:?}");
+                }
+            }
+        }
+    });
+}
+
 /// Spawns a dedicated OS thread that reads null-terminated scripts from stdin and sends them.
 /// Uses blocking I/O to avoid async stdin issues with piped input.
 fn spawn_stdin_reader(tx: mpsc::Sender<String>) {
@@ -419,42 +486,59 @@ async fn main() -> Result<(), Box<dyn std::error::Error + Send + Sync>> {
     // Server mode (default)
     let addr = args.addr.expect("addr required for server mode");
 
-    // Determine script source: -c flag, stdin (-), or file
-    let (script_content, read_stdin) = match (&args.script, &args.commands) {
-        (Some(_), Some(_)) => {
+    // Create base engine with commands, signals, and plugins
+    let base_engine = create_base_engine(interrupt.clone(), &args.plugins, &args.include_paths)?;
+
+    // Create channel for scripts
+    let (tx, rx) = mpsc::channel::<String>(1);
+
+    // Determine script source and set up appropriate watcher/reader
+    match (&args.script, &args.commands, args.watch) {
+        (Some(_), Some(_), _) => {
             eprintln!("Error: cannot specify both script file and --commands");
             std::process::exit(1);
         }
-        (None, None) => {
+        (None, None, _) => {
             eprintln!("Error: provide a script file or use --commands");
             std::process::exit(1);
         }
-        (None, Some(cmd)) => (Some(cmd.clone()), false),
-        (Some(path), None) if path == "-" => (None, true),
-        (Some(path), None) => {
+        // -c flag: use command content directly (conflicts_with prevents -w)
+        (None, Some(cmd), false) => {
+            tx.send(cmd.clone())
+                .await
+                .expect("channel closed unexpectedly");
+            drop(tx);
+        }
+        // stdin without -w: error
+        (Some(path), None, false) if path == "-" => {
+            eprintln!("Error: stdin mode (-) requires --watch flag");
+            std::process::exit(1);
+        }
+        // stdin with -w: spawn stdin reader for null-terminated scripts
+        (Some(path), None, true) if path == "-" => {
+            spawn_stdin_reader(tx);
+        }
+        // file without -w: read once
+        (Some(path), None, false) => {
             let content = std::fs::read_to_string(path).unwrap_or_else(|e| {
                 eprintln!("Error reading {path}: {e}");
                 std::process::exit(1);
             });
-            (Some(content), false)
+            tx.send(content).await.expect("channel closed unexpectedly");
+            drop(tx);
         }
-    };
-
-    // Create base engine with commands, signals, and plugins
-    let base_engine = create_base_engine(interrupt.clone(), &args.plugins, &args.include_paths)?;
-
-    // Create channel for scripts
-    let (tx, rx) = mpsc::channel::<String>(1);
-
-    if read_stdin {
-        // Spawn dedicated stdin reader thread
-        spawn_stdin_reader(tx);
-    } else {
-        // Send the script content
-        tx.send(script_content.unwrap())
-            .await
-            .expect("channel closed unexpectedly");
-        drop(tx); // Close the channel
+        // file with -w: read initial content and spawn file watcher
+        (Some(path), None, true) => {
+            let script_path = PathBuf::from(path);
+            let content = std::fs::read_to_string(&script_path).unwrap_or_else(|e| {
+                eprintln!("Error reading {path}: {e}");
+                std::process::exit(1);
+            });
+            tx.send(content).await.expect("channel closed unexpectedly");
+            spawn_file_watcher(script_path, tx);
+        }
+        // -c with -w is prevented by clap conflicts_with
+        (None, Some(_), true) => unreachable!(),
     }
 
     serve(