Module watch 

Filesystem-watcher subsystem for --watch DIR mode.

Boots a debounced recursive watcher on the configured directory and invokes a caller-supplied callback when files change. Downstream binaries register callbacks to drive whatever rebuild they need — kglite-mcp-server, for example, wires this to code_tree::build() against the watched directory and atomic-swaps the active graph.

mcp-methods’s binary on its own does not own a rebuild target; it logs change events at INFO level and forwards them to any registered callback. When no callback is set the watcher still runs, so the change events show up in stderr.

Default skip patterns

Events matching conventional noise paths (DEFAULT_SKIP_SUBSTRINGS and DEFAULT_SKIP_EXTENSIONS) are dropped before the callback runs — .git/, target/, node_modules/, __pycache__/, *.pyc, editor swap files, etc. A wide sandbox under active development generates hundreds of these per second; without the filter every consumer either rebuilds wastefully or implements the same skip list. With it, consumers see only events that could plausibly matter.

Bindings that need everything (test fixtures, future consumers with a genuine reason to see every event) pass WatchConfig::unfiltered to watch_with_config.

Structs

WatchConfig

Configuration for a watch_with_config call. Controls which events reach the callback.

WatchHandle

Active watcher handle. Drop to stop watching.

Constants

DEFAULT_DEBOUNCE

Default debounce window — short enough to feel responsive, long enough to coalesce noisy editor saves and IDE temp-file dance.

DEFAULT_SKIP_EXTENSIONS

Default file extensions to skip (without the leading dot).

DEFAULT_SKIP_SUBSTRINGS

Default substrings to skip. A path containing any of these as a substring is dropped before the callback runs.

Functions

watch

Spawn a recursive debounced watcher on dir using the default WatchConfig (skips conventional noise paths — .git/, target/, node_modules/, etc.).

watch_with_config

Spawn a recursive debounced watcher with an explicit WatchConfig. Behaves like watch except the skip set is caller-controlled — pass WatchConfig::unfiltered to receive every event, or build a custom config to add / remove patterns.

Type Aliases

ChangeHandler

Callback invoked on a debounced file-change event.