feature: Add cross-platform filesystem watcher (IOWatch)

[xerial]

Summary

• Add IOWatch API to wvlet.uni.io for watching directories for file creation, modification, and deletion events
• JVM implementation uses java.nio.file.WatchService with daemon thread polling
• Node.js (Scala.js) implementation uses fs.watch API with recursive support
• Scala Native implementation uses polling-based approach (periodic directory scanning)
• Browser platform throws UnsupportedOperationException (not supported)
• Export IOWatch.watch through the IO facade object

API

val watcher = IOWatch.watch(IOPath("my-dir"), WatchOptions(recursive = true)) { event =>
  println(s"${event.eventType}: ${event.path}")
}
watcher.close()  // Stop watching

Test plan

• Cross-platform unit tests (WatchOptions, WatchEventType, WatchEvent construction)
• JVM integration tests: file creation, modification, deletion detection
• JVM test: watcher close/cleanup
• JVM test: error on non-directory path
• JVM test: IO.watch delegation
• Scala.js tests pass (shared API tests)
• Scala Native tests pass (shared API tests)
• scalafmtAll passes
• Full compilation across all platforms

🤖 Generated with Claude Code

[xerial]

/gemini review

[gemini-code-assist]

Code Review

This pull request introduces a cross-platform file system watcher (IOWatch) with implementations for JVM (using java.nio.file.WatchService), Node.js (using fs.watch), and Scala Native (using a polling-based approach). Feedback focuses on improving the robustness of the JVM implementation by recursively registering newly created directories and protecting the background watcher thread from exceptions thrown in user-provided handlers. Additionally, there are suggestions to address platform-specific limitations of Node.js recursive watching on Linux and to improve the API usability by ensuring default arguments are correctly inherited in the IOWatch object.

[gemini-code-assist]

When a new directory is created in recursive mode, simply registering the directory itself is insufficient if that directory already contains subdirectories (e.g., during a cp -r or a move operation). To ensure all nested items are watched, you should perform a recursive walk to register all subdirectories found within the newly created path.

                    Files.walkFileTree(
                      fullPath,
                      new SimpleFileVisitor[Path]:
                        override def preVisitDirectory(dir: Path, attrs: BasicFileAttributes): FileVisitResult = 
                          registerDirectory(dir)
                          FileVisitResult.CONTINUE
                    )

[gemini-code-assist]

Node.js fs.watch throws an ERR_FEATURE_UNAVAILABLE_ON_PLATFORM error on Linux when the recursive option is set to true. Since this is a cross-platform library, you should handle this to avoid a crash. Consider checking the platform and either falling back to non-recursive watching (perhaps with a warning) or implementing manual recursion for Linux environments.

[gemini-code-assist]

The watch method in the IOWatch object should include the default value for the options parameter to match IOWatchBase. In Scala, default arguments are not automatically inherited by overriding methods in a way that makes them available when calling the method on the overriding object directly. Adding it here allows users to call IOWatch.watch(path) { ... } without explicitly providing WatchOptions.default.

  override def watch(path: IOPath, options: WatchOptions = WatchOptions.default)(handler: WatchEvent => Unit): IOWatcher =

[gemini-code-assist]

The handler callback is executed within the watcher's background thread. If the user-provided handler throws an unhandled exception, it will cause the watcher thread to terminate silently, stopping all further event processing. It is safer to wrap the handler call in a try-catch block to ensure the watcher remains resilient to errors in user code.

                  try
                    handler(WatchEvent(eventType, ioPath))
                  catch
                    case e: Throwable =>
                      // Prevent user code exceptions from killing the watcher thread
                      ()

[gemini-code-assist]

Code Review

This pull request introduces a cross-platform file system watcher API, IOWatch, with implementations for JVM, Node.js, and Scala Native. The JVM implementation uses java.nio.file.WatchService, the Node.js version utilizes fs.watch, and the Native version employs a polling-based approach. Feedback highlights the need to address platform-specific limitations of recursive watching in Node.js and to ensure the watcher remains persistent to prevent premature process exit. Additionally, for the JVM implementation, it is recommended to recursively register subdirectories when a new directory tree is created to maintain consistent behavior across all platforms.

[gemini-code-assist]

There are two concerns with the watchOptions configuration:

1. Recursive support: Node.js fs.watch only supports the recursive option on macOS and Windows. On Linux, this implementation will silently fail to watch subdirectories recursively. For a cross-platform library, it is recommended to either implement a manual recursive watcher for Linux or clearly document this platform-specific limitation.
2. Persistence: Setting persistent = false means the Node.js event loop will not stay active if this watcher is the only remaining task. Typically, file watchers are expected to keep the process alive (e.g., in build tools or dev servers) until explicitly closed. Setting persistent = true (the default in Node.js) is generally more appropriate for this API.

    val watchOptions = js.Dynamic.literal(recursive = options.recursive, persistent = true)

[gemini-code-assist]

When a new directory is created in recursive mode, only the top-level directory is registered for watching. If a directory tree is moved into the watched path or created with mkdir -p, subdirectories of the new directory will not be monitored. Using Files.walkFileTree ensures that all subdirectories within the newly created path are also registered.

                  if options.recursive && kind == ENTRY_CREATE && Files.isDirectory(fullPath) then
                    Files.walkFileTree(
                      fullPath,
                      new SimpleFileVisitor[Path]:
                        override def preVisitDirectory(dir: Path, attrs: BasicFileAttributes): FileVisitResult =
                          registerDirectory(dir)
                          FileVisitResult.CONTINUE
                    )