Resource Watcher Laravel Package

Product Decisions This Supports

• Build vs. buy for filesystem change detection. Any roadmap item that needs to react to file changes—cache invalidation on template edits, asset rebuild triggers, config drift detection, dev-loop automation—puts this package on the table as a "buy" candidate. At 7 stars, 0 dependents, and no visible maintenance cadence, it does not de-risk that decision. Frame it as "adopt a maintained alternative, build a thin wrapper ourselves, or take on internal ownership of this," not as an off-the-shelf win.
• Feature scoping and prioritization. Resource watching is enablement, never a differentiator. It belongs inside a larger feature as an implementation detail, never as a standalone roadmap line. Decision rule: if the feature isn't worth building with the watcher removed, the watcher isn't the value—the feature is.
• Legacy Cartalyst estate decisions. If the codebase already carries Cartalyst packages, this is a small, permissively licensed (BSD-2-Clause) dependency with a narrow surface. The real product decision is keep, fork, or replace—not greenfield adoption.
• Use cases worth validating against alternatives: non-Vite asset regeneration in a Laravel build, config/template change detection for long-running workers, and developer watch loops. It does not support production-scale filesystem monitoring, and it does not belong in a customer-facing request path.
• Platform-parity risk on the roadmap. The implementation leans on the Linux-only inotify extension. That makes cross-platform developer tooling a product-visible constraint (macOS/Windows teammates, Docker Desktop bind mounts), not just an engineering detail—budget for a fallback or a documented OS limitation before committing.
• Risk register entry. Low adoption cost, low signal. No downstream ecosystem to inherit fixes, no support contract, no release cadence to rely on. If adopted, the team owns it—name an owner before merge and keep the exit cheap.

When to Consider This Package

Worth evaluating when:

• You are already inside the Cartalyst ecosystem and value dependency consistency over ecosystem traction.
• You need polling-based watching—containers, network mounts, or environments where inotify/fswatch is unavailable or unreliable—or your team accepts the Linux-only constraint for dev tooling with a documented fallback.
• The requirement is genuinely small: a few watched paths, latency-tolerant, in dev or internal tooling rather than a high-frequency production path.
• You want a permissive license with minimal obligations (BSD-2-Clause) and a tiny dependency footprint that is easy to read, fork, and remove.
• You need a reference implementation to study before building your own—its most defensible value here is pedagogical.

Look elsewhere when:

• You are starting a new Laravel app. The modern default is a maintained watcher (e.g., spatie/file-system-watcher, which wraps fswatch) or, for frontend assets, letting Vite/Node tooling watch entirely.
• You need production reliability, active maintenance, security patching, a support path, or a documented contributor base. Single-digit stars and zero dependents are a maintenance-risk signal, not a quality verdict.
• You need event-driven, low-CPU behavior at scale. Polling (or per-descriptor inotify) costs and limits scale with watch breadth; native tooling does not.
• Your team spans macOS, Windows, and Linux and expects consistent behavior from required dev tooling without per-OS instructions.
• You expect out-of-the-box Laravel integration (publishable config, facades, service provider) without wiring it yourself—verify against src/ and the composer constraints before assuming.

How to Pitch It (Stakeholders)

To executives: This is a small, permissively licensed utility for detecting file changes. It is not a strategic dependency and carries no meaningful standalone upside—its only value is inside a larger feature that needs to know when files change. Adoption cost is low, but so is confidence: the project shows no ecosystem traction, so treat it as "we own it if we use it." Recommendation: do not build a roadmap item around it. If a feature needs watching, evaluate it as one option against maintained alternatives and default to those unless we have a specific reason (existing Cartalyst usage, or a polling requirement where native watchers are unavailable).

To engineering: It is a thin, framework-agnostic watcher with a clean, small API and no lock-in—easy to read, easy to fork, and, best of all, easy to remove. That removability is the core argument for adopting it at all. The trade-offs must be explicit: we accept internal ownership (pin the version, plan for PHP upgrade compatibility), a Linux-only inotify dependency that is unreliable through Docker Desktop bind mounts, and the operational sharp edges (watch limits surfacing as ENOSPC, atomic-save events arriving as delete+create, no debouncing out of the box). Before adopting, confirm that spatie/file-system-watcher or Vite/Node tooling doesn't already cover the use case—in most modern Laravel stacks it will. If we do adopt: put it behind our own small watcher interface so no domain code imports the package namespace, pilot it in a dev-only command or non-critical automation with an ignore list (vendor/, node_modules, .git, storage/*) and debounce config, and keep a documented polling fallback. Promote to production only with health checks, structured logging, a restart policy, and a named internal owner.