Refactor watcher and server with improved error handling

[hashrock]

Summary

This PR refactors the file watcher and development server code to improve maintainability, reduce duplication, and enhance error handling through better abstraction and constant management.

Key Changes

Watcher Module (watcher.js)

• Extracted debounce utility function to centralize debouncing logic used across multiple watchers, eliminating code duplication
• Created afterRebuild helper function to consolidate post-rebuild operations (onRebuild callback + WebSocket broadcast)
• Simplified createWebSocketServer by removing intermediate variables and consolidating error handling with ERROR_CODES.PORT_IN_USE constant
• Refactored watchFiles to use the new debounce and afterRebuild utilities, creating separate rebuildPage, rebuildAll, and regenerateBarrel handlers
• Refactored watchFile to use the new debounce and afterRebuild utilities
• Improved error handling by catching errors in debounced functions rather than in individual watchers

Dev Command (dev.js)

• Simplified initial build logic using ternary operator and consistent array handling
• Removed redundant port fallback logic (now handled by createDevServer)
• Consolidated watch options into a single watchOpts object
• Simplified mode and indexFile determination with cleaner conditional logic
• Removed try-catch for port conflicts as this is now handled in the server module

Server Module (server.js)

• Moved port conflict handling from dev command into createDevServer for better separation of concerns
• Implemented recursive port retry logic when EADDRINUSE error occurs
• Simplified request handler by extracting file path logic and reducing nested conditionals
• Used ERROR_CODES constant for error code comparisons
• Improved error handling with cleaner conditional flow

Constants Module (constants.js)

• Added ERROR_CODES object to centralize Node.js error code constants (EADDRINUSE, ENOENT)

Renderer Module (renderer.js)

• Removed JSDoc comments from internal helper functions for brevity
• Extracted renderChildren helper function to reduce duplication
• Simplified conditional logic using optional chaining (?.) and early returns
• Improved code readability with more concise implementations

Builder Module (builder.js)

• Refactored buildFiles to use Promise.all for parallel file building instead of sequential processing
• Improved logging by separating the logging loop from the build execution

Notable Implementation Details

• Error codes are now centralized in constants, making them easier to maintain and reference across modules
• The debounce function properly handles async operations and logs errors instead of throwing, preventing watcher crashes
• Port conflict handling is now recursive, allowing automatic fallback to the next available port
• File building in buildFiles now happens in parallel for better performance

https://claude.ai/code/session_01CYi7ea5Fdbr3EkhhowSfdG