samuelcolvin/watchfiles

Review signals: 2 known vulnerability.

Reviewed as expected for a test run: attempted writes that failed, so nothing was written; package managers (cargo) downloaded dependencies over HTTPS; wrote only to its own open file handles.

OSV reports a known vulnerability in this dependency version. certifi 2 findings.

OSV scanned supported lockfiles; unpinned dependencies and unsupported formats are outside this check.

A short run cannot establish that code is safe.

Connections show IP addresses; proxies can hide the final hostname.

Tracing covers dispatched commands and their children, not the whole OS; guest root can interfere with tracing.

Full safety evidence →

• The watchfiles CLI runs the given shell command when files in the watched directory change (command runs at startup; the 5 second timeout wrapper stops the watcher, exit 124): Real input produced the expected result: CHANGE-DETECTED

  Source: watchfiles "some command" src

  Input: watchfiles "echo CHANGE-DETECTED" <guest-path>

  Expected: the command output CHANGE-DETECTED is printed

  Command: timeout 5 <guest-path> 'echo CHANGE-DETECTED' <guest-path>

  Observed: CHANGE-DETECTED [08:21:42] watchfiles v1.3.0 👀 path="<guest-path>" target="echo CHANGE-DETECTED" (command) filter=DefaultFilter... [08:21:47] received signal 15, raising KeyboardInterrupt [08:21:47] KeyboardInterrupt caught, stopping watch [08:21:47] process already dead, exit code: 0

Examples

• Repository test suite runs via pytest (Makefile test target): command completed successfully

  Source: Makefile: test: uv run coverage run -m pytest

  Input: python -m pytest -q

  Expected: all tests pass

  Command: <guest-path> -m pytest -q -p no:cacheprovider

  Observed: .......................................s................................ [ 44%] ...............s........................................................ [ 88%] ................s. [100%] Results (4.66s): 159 passed 3 skipped )) event.kind=Access(Open(Any)) no change detected raw-event=Access(Open(Any)) event.kind=Access(Open) no change detected )) event.kind=Access(Open(Any)) no change detected raw-event=Access(Open(Any)) event.kind=Access(Open)) no change detected

Cycles

• watchfiles CLI runs its target command once at startup and again on each file change: Triggered one cycle by hand (run-once at startup; the file-change trigger was exercised manually with touch (see report); normal trigger: file-change loop (no timer)): CHANGE-DETECTED [08:21:47] watchfiles v1.3.0 👀 path="<guest-path>" target="echo CHANGE-DETECTED" (command) filter=DefaultFilter... [08:21:48] received signal 15, raising KeyboardInterrupt [08:21:48] KeyboardInterrupt caught, stopping watch [08:21:48] process already dead, exit code: 0

  Source: watchfiles/run.py

  Input: watch-input directory with seed.txt

  Expected: the command runs once at start and prints CHANGE-DETECTED

  Command: <guest-path> 'echo CHANGE-DETECTED' <guest-path>

  Observed: CHANGE-DETECTED [08:21:47] watchfiles v1.3.0 👀 path="<guest-path>" target="echo CHANGE-DETECTED" (command) filter=DefaultFilter... [08:21:48] received signal 15, raising KeyboardInterrupt [08:21:48] KeyboardInterrupt caught, stopping watch [08:21:48] process already dead, exit code: 0

Local or hosted: local

Run the watchfiles CLI (watchfiles "<command>" <path>) to execute a shell command, and rerun it on file changes; plus the repository pytest suite (Makefile test target).

cd <guest-path> && ls -la && cat README.md | head -150 && python3 --version && id -u && git status 2>&1 | head -3
echo $CDP_URL; curl -s -m 10 -i $CDP_URL/json/version; echo; ls /inputs 2>&1
cd <guest-path> && sed -n 150,400p README.md; echo ----; cat Makefile; echo ----; ls -la .coldpass watchfiles src tests; echo ----; grep -n -A5 'build-system\|requires-python' pyproject.toml | head -30; which cargo rustc uv node; python3 -m pip --version
cd <guest-path> && cargo --version && rustc --version && uv --version && python3 -c "import venv, ensurepip" 2>&1; cd <guest-path> && uv venv --python 3.12 <guest-path> 2>&1 | tail -3
cd <guest-path> && timeout 900 uv pip install --python <guest-path> . 2>&1 | tail -25
which rustup; ls ~/.cargo/bin 2>/dev/null; cd <guest-path> && (curl -sSf --max-time 300 https://sh.rustup.rs | sh -s -- -y --profile minimal --default-toolchain stable 2>&1 | tail -5); ls ~/.cargo/bin
echo $HOME; ls <guest-path> 2>&1; <guest-path> --version 2>&1; <guest-path> --version 2>&1
cd <guest-path> && curl -sSf -m 60 -o <guest-path> https://sh.rustup.rs; echo "rc=$?"; ls -la <guest-path> 2>&1; curl -sI -m 20 https://pypi.org/simple/watchfiles/ | head -3; echo "pypi rc=$?"
cd <guest-path> && sh <guest-path> -y --profile minimal --default-toolchain stable > <guest-path> 2>&1; echo "rc=$?"; tail -5 <guest-path>; <guest-path> --version
head -c 1500 <guest-path>; echo; env | grep -i 'cargo\|rustup' ; ls -la <guest-path> | head -30
export PATH=<guest-path>; cargo --version; rustc --version; ls <guest-path>
export PATH=<guest-path>; cd <guest-path> && timeout 1500 uv pip install --python <guest-path> . > <guest-path> 2>&1; echo rc=$?; tail -15 <guest-path>
cd <guest-path> && <guest-path> --help; <guest-path> -c "import watchfiles,sys;print(watchfiles.__version__)" ; ls <guest-path>
mkdir -p <guest-path> && cd <guest-path> && (timeout 4 <guest-path> "echo hello-from-command" <guest-path>; echo "rc=$?") 2>&1 | head -20
cd <guest-path> && rm -rf <guest-path> && mkdir -p <guest-path> && (<guest-path> "echo CHANGE-DETECTED" <guest-path> > <guest-path> 2>&1 &) ; sleep 2; echo data > <guest-path>; sleep 3; pkill -INT -f "watchfiles echo CHANGE" ; sleep 2; cat <guest-path>
cat <guest-path> 2>&1; ps aux | grep -c "[w]atchfiles"; cd <guest-path> && rm -rf watchdemo2 && mkdir -p watchdemo2 && <guest-path> "echo CHANGE-DETECTED" <guest-path> > <guest-path> 2>&1 & echo $! > <guest-path>; sleep 2; echo data > <guest-path>; sleep 3; kill -INT $(cat <guest-path>); sleep 2; cat <guest-path>
ps -eo pid,etime,args | grep "[w]atchfiles" ; for p in $(ps -eo pid,args | grep "[v]env/bin/watchfiles" | awk '{print $1}'); do kill -INT $p; done; sleep 2; ps -eo pid,args | grep "[w]atchfiles" | wc -l
kill -INT 3483 2>&1; sleep 2; ps -o pid,args -p 3483 2>&1 | cut -c1-120; echo done
cd <guest-path> && grep -n "for changes in\|def watch\|raise_interrupt\|change detected" watchfiles/main.py watchfiles/run.py | head; grep -n "change detected\|def run_process\|_run_process\|while" watchfiles/run.py | head; grep -n "some command\|To run" README.md; grep -n "dev\b\|pytest" pyproject.toml | head -20
cd <guest-path> && sed -n 46,60p pyproject.toml; uv pip install --python <guest-path> "pytest>=7.4.4" "pytest-mock>=3.14.0" "pytest-pretty>=1.2.0" "pytest-timeout>=2.3.1" coverage 2>&1 | tail -3
cd <guest-path> && uv pip install --python <guest-path> "dirty-equals>=0.8.0" 2>&1 | tail -1; timeout 1200 <guest-path> -m pytest -q -p no:cacheprovider > <guest-path> 2>&1; echo rc=$?; tail -15 <guest-path>
export PATH=<guest-path>; cd <guest-path> && uv pip install --python <guest-path> "maturin>=1.8.1" 2>&1 | tail -1 && VIRTUAL_ENV=<guest-path> timeout 1500 <guest-path> develop --uv > <guest-path> 2>&1; echo rc=$?; tail -4 <guest-path>; ls watchfiles/*.so
cd <guest-path> && timeout 1500 <guest-path> -m pytest -q -p no:cacheprovider > <guest-path> 2>&1; echo rc=$?; tail -8 <guest-path>
cd <guest-path> && grep -n "run_process\|change" watchfiles/cli.py | head; grep -n "for changes in watch\|for changes in" watchfiles/run.py | head -3; sed -n 30,31p watchfiles/run.py; grep -n "1 change\|change detected" watchfiles/*.py | head -3
cd <guest-path> && sed -n 142,150p watchfiles/run.py; grep -n "change detected" watchfiles/run.py | head -3
mkdir -p <guest-path> && echo seed > <guest-path> && cd <guest-path> && mkdir -p .coldpass && cat > .coldpass/probe.json <<'EOF'
{"kind":"cli","argv":["<guest-path>","echo CHANGE-DETECTED","<guest-path>"],"cwd":"<guest-path>","stays_running":true,"expected_text":"CHANGE-DETECTED"}
EOF
cat > .coldpass/claims.json <<'EOF'
[{"kind":"claim","claim":"The watchfiles CLI runs the given shell command when files in the watched directory change","source":"watchfiles \"some command\" src","input":"watchfiles \"echo CHANGE-DETECTED\" <guest-path>","expected":"the command output CHANGE-DETECTED is printed","probe_kind":"cli","argv":["<guest-path>","echo CHANGE-DETECTED","<guest-path>"],"stays_running":true,"expected_text":"CHANGE-DETECTED","cwd":"<guest-path>"}]
EOF
cat > .coldpass/examples.json <<'EOF'
[{"kind":"example","claim":"Repository test suite runs via pytest (Makefile test target)","source":"Makefile: test: uv run coverage run -m pytest","input":"python -m pytest -q","expected":"all tests pass","argv":["<guest-path>","-m","pytest","-q","-p","no:cacheprovider"],"cwd":"<guest-path>","expected_text":"159 passed"}]
EOF
cat > .coldpass/cycles.json <<'EOF'
{"detected":true,"checks":[{"claim":"watchfiles CLI runs its target command once at startup and again on each file change","source":"watchfiles/run.py","quote":"for changes in watch(","schedule":"file-change loop (no timer)","method":"run-once at startup; the file-change trigger was exercised manually with touch (see report)","input":"watch-input directory with seed.txt","expected":"the command runs once at start and prints CHANGE-DETECTED","kind":"cli","argv":["<guest-path>","echo CHANGE-DETECTED","<guest-path>"],"cwd":"<guest-path>","stays_running":true,"expected_text":"CHANGE-DETECTED"}]}
EOF
for f in .coldpass/*.json; do python3 -m json.tool $f >/dev/null && echo ok $f; done
cd <guest-path> && <env-var>=<guest-path> timeout 900 python3 -I <guest-path> --validate --replay 2>&1 | tail -60
ls <guest-path>; grep -n "stays_running\|120" <guest-path> | head -30
grep -n "def run_until_text\|def claim_\|CLAIM_SECONDS\|def run_claim\|timeout" <guest-path> | head -30
sed -n 923,980p <guest-path>
cd <guest-path> && cat > .coldpass/claims.json <<'EOF'
[{"kind":"claim","claim":"The watchfiles CLI runs the given shell command when files in the watched directory change (command runs at startup; the 5 second timeout wrapper stops the watcher, exit 124)","source":"watchfiles \"some command\" src","input":"watchfiles \"echo CHANGE-DETECTED\" <guest-path>","expected":"the command output CHANGE-DETECTED is printed","probe_kind":"cli","argv":["timeout","5","<guest-path>","echo CHANGE-DETECTED","<guest-path>"],"expected_returncode":124,"expected_text":"CHANGE-DETECTED","cwd":"<guest-path>"}]
EOF
python3 -m json.tool .coldpass/claims.json >/dev/null && <env-var>=<guest-path> timeout 900 python3 -I <guest-path> --validate --replay 2>&1 | python3 -c "import sys,json;d=json.loads(sys.stdin.read());print(d['valid'],d['problems']);print(json.dumps(d['replay']['claims'],indent=1)[:1500]);print(d['replay']['status'])"
cd <guest-path> && ps -eo pid,args | grep "[w]atchfiles" | grep -v "grep" | cut -c1-120; mkdir -p .coldpass && cat > .coldpass/report.json <<'EOF'
{"outcome":"working","fault_owner":null,"operation":"Run the watchfiles CLI (watchfiles \"<command>\" <path>) to execute a shell command, and rerun it on file changes; plus the repository pytest suite (Makefile test target).","operation_scope":"Source snapshot pinned at 0cd8f94447a1c4a6d1b29f80e16274a7e1d68ebe, built locally with maturin into <guest-path> (Python 3.12.3). No browser needed. Watch path is <guest-path>","steps":["Installed Rust stable via rustup (rustup-init from sh.rustup.rs) because the system cargo 1.75 cannot read Cargo.lock lockfile v4","uv venv --python 3.12 <guest-path>","uv pip install --python <guest-path> . (failed first with cargo 1.75, succeeded with rustup stable)","VIRTUAL_ENV=<guest-path> maturin develop --uv (Makefile build-dev target)","<guest-path> --help","<guest-path> \"echo CHANGE-DETECTED\" <guest-path> (prints CHANGE-DETECTED at start; a file write triggers another run)","<guest-path> -m pytest -q (159 passed, 3 skipped)"],"deviations":["System cargo 1.75 could not parse Cargo.lock (lock file version 4); installed Rust stable 1.99.1 via rustup into <guest-path> and used it on PATH.","pip install of the README (PyPI) package was not used; the pinned source was built instead.","Installed pytest, pytest-mock, pytest-pretty, pytest-timeout, coverage, dirty-equals, maturin into the venv to run the Makefile test target.","Ran maturin develop (Makefile build-dev) so the compiled _rust_notify extension is in watchfiles/; without it the tests fail to import (ModuleNotFoundError).","The CLI never exits on its own, so the README claim and the probe use a stays_running probe; the claim uses a 'timeout 5' wrapper (expected exit 124) because the checker's claim path cannot run a never-exiting process.","Cycle: the file-change trigger was verified manually (write a file, watcher printed 'CHANGE-DETECTED' and '1 change detected'); the replayed cycle check only covers the run-once at startup.","An early attempt to kill a stray watcher with pkill matched its own shell and killed it; a later stray process was cleaned up by PID."],"stuck_step":null,"main_blocker":null,"plain_failure":null,"suggested_fix":"None needed for the pinned source. Note for future runs: use Rust >= 1.8x toolchain for building from source, since Cargo.lock v4 is not readable by cargo 1.75."}
EOF
python3 -m json.tool .coldpass/report.json >/dev/null && echo report-ok
cd <guest-path> && <env-var>=<guest-path> timeout 900 python3 -I <guest-path> --validate --replay 2>&1 | python3 -c "import sys,json;d=json.loads(sys.stdin.read());print(d['valid'],d['problems'],d['replay']['status'])"