feat(check): add watch mode with configurable debounce

crates/vp_cli_snapshots/tests/cli_snapshots/fixtures/command_check_help/snapshots/command_check_help.md

@@ -14,6 +14,8 @@ Arguments:
 
 Options:
   --fix                            Auto-fix format and lint issues
+  --watch                          Re-run checks when workspace files change (cannot be used with --fix)
+  --debounce <MS>                  Wait for changes to stop before checking (default: <duration>; requires --watch)
   --quiet                          Disable reporting on warnings, only errors are reported
   --deny-warnings                  Treat lint warnings as errors
   --no-fmt                         Skip format check
@@ -24,6 +26,7 @@ Options:
 Examples:
   vp check
   vp check --fix
+  vp check --watch --debounce 500
   vp check --no-lint src/index.ts
 
 Documentation: https://viteplus.dev/guide/check
@@ -43,6 +46,8 @@ Arguments:
 
 Options:
   --fix                            Auto-fix format and lint issues
+  --watch                          Re-run checks when workspace files change (cannot be used with --fix)
+  --debounce <MS>                  Wait for changes to stop before checking (default: <duration>; requires --watch)
   --quiet                          Disable reporting on warnings, only errors are reported
   --deny-warnings                  Treat lint warnings as errors
   --no-fmt                         Skip format check
@@ -53,6 +58,7 @@ Options:
 Examples:
   vp check
   vp check --fix
+  vp check --watch --debounce 500
   vp check --no-lint src/index.ts
 
 Documentation: https://viteplus.dev/guide/check
@@ -72,6 +78,8 @@ Arguments:
 
 Options:
   --fix                            Auto-fix format and lint issues
+  --watch                          Re-run checks when workspace files change (cannot be used with --fix)
+  --debounce <MS>                  Wait for changes to stop before checking (default: <duration>; requires --watch)
   --quiet                          Disable reporting on warnings, only errors are reported
   --deny-warnings                  Treat lint warnings as errors
   --no-fmt                         Skip format check
@@ -82,6 +90,7 @@ Options:
 Examples:
   vp check
   vp check --fix
+  vp check --watch --debounce 500
   vp check --no-lint src/index.ts
 
 Documentation: https://viteplus.dev/guide/check

crates/vp_cli_snapshots/tests/cli_snapshots/fixtures/command_no_color/snapshots/command_no_color.global.md

@@ -14,6 +14,8 @@ Arguments:
 
 Options:
   --fix                            Auto-fix format and lint issues
+  --watch                          Re-run checks when workspace files change (cannot be used with --fix)
+  --debounce <MS>                  Wait for changes to stop before checking (default: <duration>; requires --watch)
   --quiet                          Disable reporting on warnings, only errors are reported
   --deny-warnings                  Treat lint warnings as errors
   --no-fmt                         Skip format check
@@ -24,6 +26,7 @@ Options:
 Examples:
   vp check
   vp check --fix
+  vp check --watch --debounce 500
   vp check --no-lint src/index.ts
 
 Documentation: https://viteplus.dev/guide/check

crates/vp_cli_snapshots/tests/cli_snapshots/fixtures/command_no_color/snapshots/command_no_color.local.md

@@ -14,6 +14,8 @@ Arguments:
 
 Options:
   --fix                            Auto-fix format and lint issues
+  --watch                          Re-run checks when workspace files change (cannot be used with --fix)
+  --debounce <MS>                  Wait for changes to stop before checking (default: <duration>; requires --watch)
   --quiet                          Disable reporting on warnings, only errors are reported
   --deny-warnings                  Treat lint warnings as errors
   --no-fmt                         Skip format check
@@ -24,6 +26,7 @@ Options:
 Examples:
   vp check
   vp check --fix
+  vp check --watch --debounce 500
   vp check --no-lint src/index.ts
 
 Documentation: https://viteplus.dev/guide/check

docs/guide/check.md

@@ -15,6 +15,8 @@ We recommend turning both `typeAware` and `typeCheck` on so `vp check` becomes t
 ```bash
 vp check
 vp check --fix              # Format and run autofixers.
+vp check --watch            # Re-run checks when workspace files change.
+vp check --watch --debounce 500 # Wait for 500ms of inactivity before checking.
 vp check --quiet            # Hide lint warnings; still report and fail on errors.
 vp check --deny-warnings    # Treat lint warnings as errors.
 vp check --no-fmt           # Skip format; run lint (and type-check if enabled).
@@ -26,6 +28,25 @@ If formatting fails, `vp check` stops before lint and type checks run. To fix fo
 
 Put `vp check` flags before file paths. For example, use `vp check --fix src/index.ts`. Arguments after the first path go to the format and lint tools instead of `vp check`.
 
+## Watch mode
+
+`vp check --watch` runs once on startup and then watches workspace files for changes.
+Changes are grouped until no further changes arrive for 300 milliseconds. Use
+`--debounce <ms>` with `--watch` to choose a different delay.
+
+Checks run one at a time. Changes made during a check trigger another run after
+the check completes and the debounce delay expires. Failed checks keep watching,
+so fixing an error triggers another check. Press Ctrl+C to stop.
+
+Watch mode ignores changes inside `node_modules`, `.git`, `dist`, `target`, `.vite`,
+`.cache`, and `.idea` directories, along with editor temporary and backup files.
+Repeated events for unchanged file contents do not trigger another check.
+File path arguments restrict what is checked; the watcher
+still observes the workspace so changes to configuration and shared files trigger checks.
+
+`--fix` cannot currently be combined with `--watch`. Run `vp check --fix` separately
+to apply fixes.
+
 ## Configuration
 
 `vp check` uses the same configuration you already define for linting and formatting:

packages/cli/binding/Cargo.toml

@@ -18,13 +18,14 @@ base64-simd = { workspace = true }
 clap = { workspace = true, features = ["derive"] }
 cow-utils = { workspace = true }
 rustc-hash = { workspace = true }
+rolldown-notify = { workspace = true }
 napi = { workspace = true }
 napi-derive = { workspace = true }
 petgraph = { workspace = true }
 console = { workspace = true }
 serde = { workspace = true, features = ["derive"] }
 serde_json = { workspace = true }
-tokio = { workspace = true, features = ["fs"] }
+tokio = { workspace = true, features = ["fs", "signal", "sync", "time"] }
 tracing = { workspace = true }
 uuid = { workspace = true, features = ["v4"] }
 vp_command = { workspace = true }
@@ -48,6 +49,7 @@ oxc-node = { workspace = true, optional = true }
 napi-build = { workspace = true }
 
 [dev-dependencies]
+tokio = { workspace = true, features = ["test-util"] }
 pretty_assertions = { workspace = true }
 tempfile = { workspace = true }
 vp_shared = { workspace = true, features = ["test-utils"] }

packages/cli/binding/src/check/mod.rs

@@ -1,4 +1,5 @@
 mod analysis;
+pub(crate) mod watch;
 
 use std::{sync::Arc, time::Instant};