| name | parcel |
| description | Kolu's project-wide default for filesystem monitoring is `@parcel/watcher`. Reach for this skill when adding or modifying any code that watches files or directories — recursive subtree watching, single-file observation, fs.watch alternatives, chokidar replacement, inotify/FSEvents/watchman backend selection, ignore globs, watcher debouncing, or refcounted shared subscriptions. Covers backend dispatch, the watchman invocation path, ignore handling, post-install reconciliation, and the failure modes Kolu's logger surfaces. |
@parcel/watcher integration
@parcel/watcher is Kolu's default filesystem watcher. Reach for it instead
of chokidar, raw fs.watch, or hand-rolled polling whenever a feature
needs to observe a directory subtree. Today's only consumer is the
working-tree watcher (packages/integrations/git/src/working-tree-watcher.ts)
— the git-dir watchers (head-watcher, reflog-watcher, index-watcher)
use plain fs.watch via kolu-io's refcounted-dir-watcher.ts because they
target a single known file inside .git/, where parcel-watcher's recursive
model would be overkill. New fs-monitoring code should default to parcel-watcher
unless it has a similarly narrow target.
Backend dispatch
Source: node_modules/.pnpm/@parcel+watcher@2.5.6/node_modules/@parcel/watcher/src/Backend.cc:30-69.
Kolu pins the OS-native backend explicitly (inotify / fs-events /
windows, chosen off process.platform — see PARCEL_BACKEND in
working-tree-watcher.ts). It does not use backend: "default". The pin
skips the auto-dispatch order below — most importantly the
probe, whose per-subscribe leaks a zombie on watchman-less hosts (see
next section). If you write a new parcel consumer, pin the backend the same way.
