chore(with-watch): add --clear terminal refresh mode (#377)

## Summary
- add a global `--clear` flag across passthrough, `--shell`, and `exec
--input` modes
- clear the terminal before the initial run and each rerun only when
stdout is a TTY
- document the new contract in the with-watch README and project docs

## Testing
- cargo test -p with-watch
- cargo test
- cargo run -p with-watch -- --help

Author: kdy1

crates/AGENTS.md

@@ -44,6 +44,7 @@
 
 - Keep passthrough, shell, and `exec --input` command shapes stable and documented in `docs/project-with-watch.md` and `docs/crates-with-watch-foundation.md`.
 - Keep default rerun filtering content-hash-based, with `--no-hash` as the documented metadata-only override.
+- Keep `--clear` as a best-effort TTY-only output refresh flag; redirected or piped stdout must stay byte-for-byte clean.
 - Keep shell support scoped to command-line expressions and do not silently broaden into shell-script control-flow without updating docs first.
 - Keep logs sufficient to explain inferred inputs, watcher anchors, snapshot counts, and rerun causes.
 - Keep public release contracts aligned across root publish-tag allowlist, `.github/workflows/release-with-watch.yml`, and Homebrew packaging assets.

crates/with-watch/README.md

@@ -19,16 +19,19 @@ brew install delinoio/tap/with-watch
 
 ## Command modes
 
-- Passthrough mode: `with-watch [--no-hash] <utility> [args...]`
-- Shell mode: `with-watch [--no-hash] --shell '<expr>'`
-- Explicit-input mode: `with-watch exec [--no-hash] --input <glob>... -- <command> [args...]`
+- Passthrough mode: `with-watch [--no-hash] [--clear] <utility> [args...]`
+- Shell mode: `with-watch [--no-hash] [--clear] --shell '<expr>'`
+- Explicit-input mode: `with-watch exec [--no-hash] [--clear] --input <glob>... -- <command> [args...]`
+
+All modes also accept `--clear`, which clears the terminal before the initial run and each rerun when stdout is an interactive terminal.
 
 Use passthrough mode for a single delegated command, shell mode for simple command-line expressions that need `&&`, `||`, or `|`, and `exec --input` when you want to declare the watched files yourself.
 
 ## Quick start
 
 ```sh
 with-watch cat input.txt
+with-watch --clear cat input.txt
 with-watch cp src.txt dest.txt
 with-watch ls -l
 with-watch --shell 'cat src.txt | grep hello'
@@ -104,6 +107,7 @@ with-watch exec --input 'src/**/*.rs' -- cargo test -p with-watch
 ## Rerun behavior
 
 - `with-watch` always performs one initial run after it has inferred inputs and armed the watcher, even before any external filesystem change occurs.
+- `--clear` clears stdout before the initial run and each rerun only when stdout is a terminal; redirected and piped output remain unchanged.
 - The default rerun filter compares content hashes, which avoids reruns from metadata churn alone.
 - `ls`, `dir`, and `vdir` use metadata-based listing snapshots instead of hashing every file under the watched directory before the first run.
 - `--no-hash` switches the filter to metadata-only comparison.

crates/with-watch/src/analysis.rs

@@ -494,15 +494,15 @@ pub fn render_after_long_help() -> String {
     let inventory = help_inventory();
 
     format!(
-        "Command modes:\n  Passthrough: with-watch [--no-hash] <utility> [args...]\n  Shell: \
-         with-watch [--no-hash] --shell '<expr>'\n  Explicit inputs: with-watch exec [--no-hash] \
-         --input <glob>... -- <command> [args...]\n\nWrapper commands:\n  {}\n\nDedicated \
-         built-in adapters and aliases:\n  {}\n\nGeneric read-path commands:\n  {}\n\nSafe \
-         current-directory defaults:\n  {}\n\nRecognized but not auto-watchable commands:\n  {}\n  \
-         These commands are recognized, but they do not expose stable filesystem inputs on their \
-         own.\n\nexec --input escape hatch:\n  Use `with-watch exec --input <glob>... -- \
-         <command> [args...]` when inference is ambiguous, when a command has no stable \
-         filesystem inputs, or when you want an explicit watch set.",
+        "Command modes:\n  Passthrough: with-watch [--no-hash] [--clear] <utility> [args...]\n  \
+         Shell: with-watch [--no-hash] [--clear] --shell '<expr>'\n  Explicit inputs: with-watch \
+         exec [--no-hash] [--clear] --input <glob>... -- <command> [args...]\n\nWrapper \
+         commands:\n  {}\n\nDedicated built-in adapters and aliases:\n  {}\n\nGeneric read-path \
+         commands:\n  {}\n\nSafe current-directory defaults:\n  {}\n\nRecognized but not \
+         auto-watchable commands:\n  {}\n  These commands are recognized, but they do not expose \
+         stable filesystem inputs on their own.\n\nexec --input escape hatch:\n  Use `with-watch \
+         exec --input <glob>... -- <command> [args...]` when inference is ambiguous, when a \
+         command has no stable filesystem inputs, or when you want an explicit watch set.",
         join_command_names(&inventory.wrapper_commands),
         join_command_names(&inventory.dedicated_built_ins),
         join_command_names(inventory.generic_read_path_commands),

crates/with-watch/src/cli.rs

@@ -5,6 +5,7 @@ use clap::{Args, CommandFactory, FromArgMatches, Parser, Subcommand};
 use crate::{
     analysis::render_after_long_help,
     error::{Result, WithWatchError},
+    runner::OutputRefreshMode,
     snapshot::ChangeDetectionMode,
 };
 
@@ -19,6 +20,10 @@ pub struct Cli {
     #[arg(long, global = true)]
     pub no_hash: bool,
 
+    /// Clear the terminal before the initial run and each rerun.
+    #[arg(long, global = true)]
+    pub clear: bool,
+
     /// Run a quoted shell command line that may contain `&&`, `||`, or `|`.
     #[arg(long, global = true, value_name = "EXPR")]
     pub shell: Option<String>,
@@ -78,6 +83,14 @@ impl Cli {
         }
     }
 
+    pub fn output_refresh_mode(&self) -> OutputRefreshMode {
+        if self.clear {
+            OutputRefreshMode::ClearTerminal
+        } else {
+            OutputRefreshMode::Preserve
+        }
+    }
+
     pub fn command_mode(&self) -> Result<CommandMode> {
         match (&self.shell, &self.command) {
             (Some(_), Some(_)) => Err(WithWatchError::ConflictingModes),
@@ -115,7 +128,7 @@ mod tests {
     use clap::Parser;
 
     use super::{Cli, CommandMode};
-    use crate::{error::WithWatchError, snapshot::ChangeDetectionMode};
+    use crate::{error::WithWatchError, runner::OutputRefreshMode, snapshot::ChangeDetectionMode};
 
     #[test]
     fn passthrough_mode_preserves_external_subcommand_arguments() {
@@ -142,6 +155,42 @@ mod tests {
         assert!(matches!(error, WithWatchError::ConflictingModes));
     }
 
+    #[test]
+    fn passthrough_mode_accepts_clear_flag() {
+        let cli = Cli::parse_from(["with-watch", "--clear", "cat", "input.txt"]);
+        let mode = cli.command_mode().expect("command mode");
+
+        assert_eq!(cli.output_refresh_mode(), OutputRefreshMode::ClearTerminal);
+        assert!(matches!(mode, CommandMode::Passthrough { .. }));
+    }
+
+    #[test]
+    fn shell_mode_accepts_clear_flag() {
+        let cli = Cli::parse_from(["with-watch", "--clear", "--shell", "cat input.txt"]);
+        let mode = cli.command_mode().expect("command mode");
+
+        assert_eq!(cli.output_refresh_mode(), OutputRefreshMode::ClearTerminal);
+        assert!(matches!(mode, CommandMode::Shell { .. }));
+    }
+
+    #[test]
+    fn exec_mode_accepts_clear_flag() {
+        let cli = Cli::parse_from([
+            "with-watch",
+            "exec",
+            "--clear",
+            "--input",
+            "src/**/*.rs",
+            "--",
+            "cargo",
+            "test",
+        ]);
+        let mode = cli.command_mode().expect("command mode");
+
+        assert_eq!(cli.output_refresh_mode(), OutputRefreshMode::ClearTerminal);
+        assert!(matches!(mode, CommandMode::Exec { .. }));
+    }
+
     #[test]
     fn exec_mode_uses_mtime_only_when_hashing_is_disabled() {
         let cli = Cli::parse_from([
@@ -177,7 +226,9 @@ mod tests {
 
         assert!(!short_help.contains("Wrapper commands:"));
         assert!(!short_help.contains("Recognized but not auto-watchable commands:"));
+        assert!(short_help.contains("--clear"));
         assert!(long_help.contains("Wrapper commands:"));
         assert!(long_help.contains("Recognized but not auto-watchable commands:"));
+        assert!(long_help.contains("--clear"));
     }
 }

crates/with-watch/src/error.rs

@@ -64,6 +64,8 @@ pub enum WithWatchError {
         #[source]
         source: io::Error,
     },
+    #[error("Failed to refresh stdout before running the delegated command: {0}")]
+    StdoutRefresh(#[source] io::Error),
     #[error("`--shell` execution is only supported on Unix-like platforms.")]
     UnsupportedShellPlatform,
 }
@@ -87,7 +89,8 @@ impl WithWatchError {
             | Self::WatcherCreate(_)
             | Self::WatchPath { .. }
             | Self::Spawn { .. }
-            | Self::Wait { .. } => 1,
+            | Self::Wait { .. }
+            | Self::StdoutRefresh(_) => 1,
         }
     }
 }

crates/with-watch/src/lib.rs

@@ -13,21 +13,23 @@ use analysis::{analyze_argv, analyze_shell_expression, CommandAnalysis, CommandA
 use cli::{Cli, CommandMode};
 use error::{Result, WithWatchError};
 use parser::parse_shell_expression;
-use runner::{ExecutionMetadata, ExecutionPlan, RunnerOptions};
+use runner::{ExecutionMetadata, ExecutionPlan, OutputRefreshMode, RunnerOptions};
 use snapshot::{ChangeDetectionMode, WatchInput, WatchInputKind};
 use tracing::debug;
 
 pub fn run_cli(cli: Cli, options: RunnerOptions) -> Result<i32> {
     let mode = cli.command_mode()?;
     let cwd = std::env::current_dir().map_err(WithWatchError::CurrentDirectory)?;
     let detection_mode = cli.change_detection_mode();
-    let plan = build_execution_plan(mode, detection_mode, &cwd)?;
+    let output_refresh_mode = cli.output_refresh_mode();
+    let plan = build_execution_plan(mode, detection_mode, output_refresh_mode, &cwd)?;
     runner::run(plan, options)
 }
 
 fn build_execution_plan(
     mode: CommandMode,
     detection_mode: ChangeDetectionMode,
+    output_refresh_mode: OutputRefreshMode,
     cwd: &Path,
 ) -> Result<ExecutionPlan> {
     match mode {
@@ -39,6 +41,7 @@ fn build_execution_plan(
                 argv,
                 inputs,
                 detection_mode,
+                output_refresh_mode,
                 execution_metadata(&analysis),
             ))
         }
@@ -51,6 +54,7 @@ fn build_execution_plan(
                 expression,
                 inputs,
                 detection_mode,
+                output_refresh_mode,
                 execution_metadata(&analysis),
             ))
         }
@@ -62,6 +66,7 @@ fn build_execution_plan(
                 argv,
                 planned_inputs,
                 detection_mode,
+                output_refresh_mode,
                 execution_metadata(&analysis),
             ))
         }