refactor: Add type annotations and address code review feedback

Address feedback from automated code review:

- Add JSDoc type annotations throughout dev-watch.js for better type
  safety (ProcessInfo, ChildProcess, FSWatcher types)
- Add clarifying comment explaining child_process.spawn is
  Bun-compatible (Bun supports Node.js APIs)
- Convert test file from require() to ES6 imports (readFileSync)
- Add function documentation with @param and @returns annotations

Note: child_process.spawn is intentionally kept instead of Bun.spawn
for compatibility with existing event handlers. Bun fully supports
child_process APIs. fs.watch from node:fs is the correct API to use
(native Bun.watch() doesn't exist yet).

All tests passing (8/8).

Author: wtfsayo

scripts/__tests__/dev-watch.test.ts

@@ -5,7 +5,7 @@
 import { describe, test, expect, beforeAll, afterAll } from 'bun:test';
 import { spawn, type ChildProcess } from 'child_process';
 import { writeFile, readFile, mkdir } from 'node:fs/promises';
-import { existsSync } from 'node:fs';
+import { existsSync, readFileSync } from 'node:fs';
 import path from 'path';
 
 const PROJECT_ROOT = path.resolve(__dirname, '../..');
@@ -95,8 +95,7 @@ describe('Hot Reload Functionality', () => {
 
   test('watched directories should include all CLI dependencies', () => {
     // Read the dev-watch.js file and verify it watches the right directories
-    const fs = require('node:fs');
-    const devWatchContent = fs.readFileSync(DEV_SCRIPT, 'utf-8');
+    const devWatchContent = readFileSync(DEV_SCRIPT, 'utf-8');
 
     // Check that critical packages are being watched
     const expectedPackages = [
@@ -116,8 +115,7 @@ describe('Hot Reload Functionality', () => {
 
   test('debounce mechanism should prevent rapid rebuilds', async () => {
     // This test verifies that the debounce timer is set
-    const fs = require('node:fs');
-    const devWatchContent = fs.readFileSync(DEV_SCRIPT, 'utf-8');
+    const devWatchContent = readFileSync(DEV_SCRIPT, 'utf-8');
 
     // Check for debounce implementation
     expect(devWatchContent).toContain('rebuildDebounceTimer');
@@ -126,8 +124,7 @@ describe('Hot Reload Functionality', () => {
   });
 
   test('rebuild function should stop server before rebuilding', () => {
-    const fs = require('node:fs');
-    const devWatchContent = fs.readFileSync(DEV_SCRIPT, 'utf-8');
+    const devWatchContent = readFileSync(DEV_SCRIPT, 'utf-8');
 
     // Check that rebuild logic includes server shutdown
     expect(devWatchContent).toContain('rebuildAndRestartServer');
@@ -136,17 +133,15 @@ describe('Hot Reload Functionality', () => {
   });
 
   test('file watcher should only watch TypeScript files', () => {
-    const fs = require('node:fs');
-    const devWatchContent = fs.readFileSync(DEV_SCRIPT, 'utf-8');
+    const devWatchContent = readFileSync(DEV_SCRIPT, 'utf-8');
 
     // Check that file watcher filters for TypeScript files
     expect(devWatchContent).toContain('.ts');
     expect(devWatchContent).toContain('.tsx');
   });
 
   test('cleanup should handle file watchers properly', () => {
-    const fs = require('node:fs');
-    const devWatchContent = fs.readFileSync(DEV_SCRIPT, 'utf-8');
+    const devWatchContent = readFileSync(DEV_SCRIPT, 'utf-8');
 
     // Check that cleanup includes watcher handling
     expect(devWatchContent).toContain("type === 'watcher'");

scripts/dev-watch.js

@@ -1,10 +1,18 @@
 #!/usr/bin/env bun
 
+// Note: Using child_process.spawn for compatibility with existing event handlers.
+// Bun fully supports child_process APIs. For new code, consider Bun.spawn or
+// the bun-exec utilities in packages/cli/src/utils/bun-exec.ts
 import { spawn } from 'child_process';
 import path from 'path';
 import { fileURLToPath } from 'url';
 import { watch } from 'node:fs';
 
+/** @typedef {import('node:fs').FSWatcher} FSWatcher */
+/** @typedef {import('child_process').ChildProcess} ChildProcess */
+/** @typedef {'build' | 'server' | 'client' | 'watcher'} ProcessType */
+/** @typedef {{ name: string; child: ChildProcess | FSWatcher; type: ProcessType }} ProcessInfo */
+
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 
@@ -24,20 +32,36 @@ const watchDirs = [
   path.resolve(packagesDir, 'config/src'),
 ];
 
+/** @type {ProcessInfo[]} */
 let processes = [];
+/** @type {boolean} */
 let isShuttingDown = false;
+/** @type {boolean} */
 let serverReady = false;
+/** @type {boolean} */
 let isRebuilding = false;
+/** @type {NodeJS.Timeout | null} */
 let rebuildDebounceTimer = null;
 
+/**
+ * Log a message with a prefix and timestamp
+ * @param {string} prefix - The log prefix
+ * @param {string} message - The message to log
+ */
 function log(prefix, message) {
   console.log(`[${prefix}] ${new Date().toLocaleTimeString()} - ${message}`);
 }
 
 // Simple color helpers (avoid external deps)
+/** @param {string} s */
 const cyan = (s) => `\x1b[36m${s}\x1b[0m`;
 
-// Health check function to verify server is responding
+/**
+ * Health check function to verify server is responding
+ * @param {string} [url='http://localhost:3000/api/server/ping'] - URL to check
+ * @param {number} [maxAttempts=30] - Maximum number of attempts
+ * @returns {Promise<boolean>}
+ */
 async function waitForServer(url = 'http://localhost:3000/api/server/ping', maxAttempts = 30) {
   log('HEALTH', `Waiting for server to be ready at ${url}...`);
 
@@ -70,6 +94,10 @@ async function waitForServer(url = 'http://localhost:3000/api/server/ping', maxA
   return false;
 }
 
+/**
+ * Start the Vite development server for the frontend
+ * @returns {ChildProcess}
+ */
 function startViteDevServer() {
   log('CLIENT', 'Starting Vite dev server with HMR...');
 
@@ -101,6 +129,10 @@ function startViteDevServer() {
   return child;
 }
 
+/**
+ * Start the CLI server by building and running it
+ * @returns {ChildProcess}
+ */
 function startCliServer() {
   log('CLI', 'Starting CLI server build...');