parcel

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.

backend: "default" (Kolu doesn't pass an explicit backend) selects in this order, first match wins:

1. FSEvents on macOS — native recursive, one stream per repo.
2. WatchmanBackend if WatchmanBackend::checkAvailable() returns true.
3. WindowsBackend on Windows — native recursive ReadDirectoryChangesW.
4. InotifyBackend on Linux — one inotify slot per non-ignored directory.
5. KqueueBackend on BSD.
6. BruteForceBackend — periodic full-tree stat; the fallback fallback.

So on Linux, watchman is preferred over inotify whenever it's reachable; on macOS watchman is never used by default (FSEvents wins).

How parcel invokes watchman

Source: src/watchman/WatchmanBackend.cc.

1. checkAvailable() (line 107) just calls watchmanConnect().
2. getSockPath() (line 43) does the only watchman binary invocation:

   popen("watchman --output-encoding=bser get-sockname 2>/dev/null", "r")
   

   then parses BSER output for the sockname field. If WATCHMAN_SOCK env var is set, that wins and the binary isn't run at all.
3. From there it's a Unix-domain socket carrying BSER-encoded JSON. No more subprocess spawns.

Commands (BSER arrays sent over the socket):

Source	Command	Purpose
watchmanWatch (line 100)	["watch", "/abs/dir"]	start tracking
clock (line 230)	["clock", "/abs/dir"]	get baseline clock token
subscribe (line 281)	["subscribe", "/abs/dir", "parcel-<ptr>", {fields,since,expression}]	start receiving events
unsubscribe (line 330)	["unsubscribe", "/abs/dir", id]	tear down

Subscription IDs are "parcel-" + hex(watcher-pointer). Event mapping in handleFiles (line 137):

• new && exists → create
• exists && !S_ISDIR(mode) → update
• !new && !exists → remove

Ignore globs are translated to a watchman expression ["not", ["anyof", ["dirname", rel], ...]] only for ignores that are direct subpaths of the watched root (line 300). Glob-style ignores like **/node_modules are filtered client-side after events arrive — pass them in the ignore option but don't expect watchman-side filtering.

Cookie files (.watchman-cookie-*)

Written by the watchman daemon, not parcel-watcher. The daemon drops these files inside watched dirs to verify it can observe its own writes (watch/query commands trigger the dance). Normally ephemeral. Stragglers mean the daemon was killed mid-handshake. Add .watchman-cookie-* to .gitignore if watchman is in use.

Kolu's runtime status

As of #788, Kolu does not ship watchman with the production binary. The nix run wrapper (default.nix:156) only adds nodejs git gh to PATH, so checkAvailable() always returns false at runtime and parcel falls through to inotify on Linux / FSEvents on macOS. Issue #788 tracks the integration work.

Kolu's wrapper invariants

packages/integrations/git/src/working-tree-watcher.ts:

• Refcounted shared singleton per repoRoot — N callers → one parcel subscription, listener-side filtering by optional filePath.
• Trailing-edge debounce at WATCHER_DEBOUNCE_MS (150ms) coalesces bursts into one fire per listener.
• Hard-coded IGNORE_GLOBS — .git, node_modules, dist, build, target, .next, .turbo, .cache, .parcel-cache, .kolu-dev, .kolu-state, .DS_Store. Not gitignore-aware. Over-firing on user build outputs is absorbed by the snapshot-equality check in streamSnapshots(...) upstream.
• Post-install reconciliation tick (line 176) — parcelSubscribe is async. Filesystem mutations between subscribe() call and parcel resolving are invisible to parcel; the streaming endpoint already yielded its initial snapshot. The reconciliation fires every current listener once parcel is ready, so consumers re-read state and catch the missed window. Without this the client sees a stale view that no future event corrects.
• cancelled guard on the .then — if the last subscriber unsubscribed before parcel resolved, late-unsubscribe the AsyncSubscription instead of storing it.

What Kolu logs

Watcher lifecycle through Logger (kolu-shared). Grep these strings to verify the watcher came up in production:

• info git: working-tree watcher installed ← parcel resolved successfully
• info git: working-tree watcher retired ← last subscriber gone
• error git: working-tree watcher install failed ← parcel subscribe() rejected
• error git: working-tree watcher callback error ← parcel reported event-stream error
• error git: working-tree late-unsubscribe failed
• error git: working-tree unsubscribe failed
• error git: working-tree listener threw

Individual filesystem events are not logged — too noisy. The bucket-and- debounce path swallows event paths silently.

Failure modes worth knowing

1. Container/WSL2 bind mounts — neither inotify nor FSEvents nor watchman is available. parcel-watcher silently falls back to ~1s polling. Latency degrades, correctness preserved.
2. Linux inotify slot exhaustion — kernel default is fs.inotify.max_user_watches=8192. A typical Kolu repo uses ~500–2000 slots; multiple worktrees compound. Watchman amortizes this across one daemon (#788).
3. detect-libc glibc/musl picker runs on require('@parcel/watcher') (index.js:5). The Nix build needs the matching native binary in node_modules — confirm @parcel/watcher-linux-x64-glibc is present under node_modules/.pnpm/.
4. dontFixup = true in default.nix skips patchELF on the native .node binary. Today the @parcel/watcher binary loads its own libstdc++ via fallback paths and works, but if a future parcel-watcher version pulls in a harder dynamic-link requirement, expect to revisit this.

Quick references

• Backend dispatch: node_modules/.pnpm/@parcel+watcher@2.5.6/node_modules/@parcel/watcher/src/Backend.cc:30
• Watchman invocation: node_modules/.pnpm/@parcel+watcher@2.5.6/node_modules/@parcel/watcher/src/watchman/WatchmanBackend.cc:43
• Kolu wrapper: packages/integrations/git/src/working-tree-watcher.ts
• Composed watcher API: packages/integrations/git/src/repo-change.ts
• Watchman integration issue: juspay/kolu#788
• Streaming endpoints that consume the watcher: packages/server/src/router.ts (onStatusChange, onDiffChange, onListAllChange, onReadFileChange)