fix: resolve critical cross-platform and reliability issues

Fixed two CRITICAL issues identified in code quality review:

1. Windows Path Detection Bug (Issue #4)
   - Added cross-platform path separator detection (/, \)
   - Added URL exclusion to prevent treating URLs as file paths
   - Fixed CLI being completely broken for Windows users
   - Added 7 comprehensive tests for path detection

2. Watch Service Race Condition (Issue #1)
   - Added isWatching flag to prevent race conditions
   - Prevents timer callbacks from executing after stop() called
   - Handles rapid start/stop cycles correctly
   - Added 5 comprehensive tests for race condition scenarios

Test suite: 1165 tests passing (12 new tests added for these fixes)
All fixes validated through TDD methodology (RED → GREEN → REFACTOR)

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

Author: sjsyrek

src/cli/commands/translate.ts

@@ -115,15 +115,29 @@ export class TranslateCommand {
 
   /**
    * Check if input is a file path
+   * Handles cross-platform paths (Windows backslashes and Unix forward slashes)
+   * Excludes URLs from being treated as file paths
    */
   private isFilePath(input: string): boolean {
     // Check if file exists
     if (fs.existsSync(input)) {
       return true;
     }
 
-    // If input contains file extensions, might be a file
-    return this.fileTranslationService.isSupportedFile(input) && input.includes('/');
+    // Don't treat URLs as file paths
+    // Check for common URL protocols: http://, https://, ftp://, file://
+    if (/^[a-zA-Z][a-zA-Z0-9+.-]*:\/\//.test(input)) {
+      return false;
+    }
+
+    // Check for path separators (cross-platform)
+    // Windows: backslash (\), Unix: forward slash (/)
+    const hasPathSep = input.includes(path.sep) ||
+                       input.includes('/') ||
+                       input.includes('\\');
+
+    // Must have path separator AND supported extension to be considered a file path
+    return hasPathSep && this.fileTranslationService.isSupportedFile(input);
   }
 
   /**

src/services/watch.ts

@@ -131,12 +131,21 @@ export class WatchService {
 
   /**
    * Handle file change event
+   * Uses isWatching flag to prevent race conditions with stop()
    */
   handleFileChange(filePath: string): void {
+    // Check if watch has been started at least once
     if (!this.watchOptions) {
       throw new Error('Watch not started');
     }
 
+    // Early check: Don't schedule new timers if watch is being stopped or has stopped
+    // This prevents race conditions where stop() is called between the check above
+    // and scheduling the timer below
+    if (!this.stats.isWatching) {
+      return;
+    }
+
     // Check if file is supported
     if (!this.fileTranslationService.isSupportedFile(filePath)) {
       return;
@@ -157,8 +166,9 @@ export class WatchService {
       // Wrap async code to handle Promise properly (void operator tells TypeScript we intentionally ignore the Promise)
       void (async () => {
         try {
-          // Check if watch is still active (prevent race condition with stop())
-          if (!this.watchOptions) {
+          // Double-check watch is still active (prevent race condition with stop())
+          // Use isWatching flag for reliable state checking
+          if (!this.stats.isWatching) {
             this.debounceTimers.delete(filePath);
             return;
           }

tests/unit/services/watch.test.ts

@@ -663,4 +663,157 @@ describe('WatchService', () => {
       expect(() => watchService.handleFileChange(testFile)).toThrow('Watch not started');
     });
   });
+
+  describe('race condition handling (Issue #1)', () => {
+    it('should not execute timer callback if watch is stopped after timer is scheduled', async () => {
+      jest.useFakeTimers();
+
+      const service = new WatchService(mockFileTranslationService, {
+        debounceMs: 500,
+      });
+
+      const testFile = path.join(testDir, 'test.txt');
+      fs.writeFileSync(testFile, 'Hello');
+
+      const options = {
+        targetLangs: ['es' as const],
+        outputDir: path.join(testDir, 'output'),
+      };
+
+      await service.watch(testDir, options);
+
+      // Schedule timer (file change event)
+      service.handleFileChange(testFile);
+
+      // Stop immediately (before timer fires)
+      await service.stop();
+
+      // Now advance time (timer callback should be cancelled or should check watch state)
+      jest.advanceTimersByTime(500);
+      await Promise.resolve();
+
+      // Translation should NOT occur because watch was stopped
+      expect(mockFileTranslationService.translateFile).not.toHaveBeenCalled();
+
+      jest.useRealTimers();
+    });
+
+    it('should not schedule new timers if watch is stopped', async () => {
+      const testFile = path.join(testDir, 'test.txt');
+      fs.writeFileSync(testFile, 'Hello');
+
+      const options = {
+        targetLangs: ['es' as const],
+        outputDir: path.join(testDir, 'output'),
+      };
+
+      await watchService.watch(testDir, options);
+      await watchService.stop();
+
+      // Try to trigger file change after stop
+      // Should not throw, but also should not schedule translation
+      expect(() => watchService.handleFileChange(testFile)).toThrow('Watch not started');
+    });
+
+    it('should handle rapid start/stop cycles without orphaned timers', async () => {
+      jest.useFakeTimers();
+
+      const service = new WatchService(mockFileTranslationService, {
+        debounceMs: 300,
+      });
+
+      const testFile = path.join(testDir, 'test.txt');
+      fs.writeFileSync(testFile, 'Hello');
+
+      const options = {
+        targetLangs: ['es' as const],
+        outputDir: path.join(testDir, 'output'),
+      };
+
+      // Rapid start/stop cycles
+      await service.watch(testDir, options);
+      service.handleFileChange(testFile);
+      await service.stop();
+
+      await service.watch(testDir, options);
+      service.handleFileChange(testFile);
+      await service.stop();
+
+      await service.watch(testDir, options);
+      service.handleFileChange(testFile);
+      await service.stop();
+
+      // Fast-forward all timers
+      jest.advanceTimersByTime(1000);
+      await Promise.resolve();
+
+      // No translations should occur (all timers cancelled on stop)
+      expect(mockFileTranslationService.translateFile).not.toHaveBeenCalled();
+
+      jest.useRealTimers();
+    });
+
+    it('should check watch state inside timer callback to prevent race condition', async () => {
+      jest.useFakeTimers();
+
+      const service = new WatchService(mockFileTranslationService, {
+        debounceMs: 500,
+      });
+
+      const testFile = path.join(testDir, 'test.txt');
+      fs.writeFileSync(testFile, 'Hello');
+
+      mockFileTranslationService.translateFile.mockResolvedValue(undefined);
+
+      const options = {
+        targetLangs: ['es' as const],
+        outputDir: path.join(testDir, 'output'),
+      };
+
+      await service.watch(testDir, options);
+      service.handleFileChange(testFile);
+
+      // Fast-forward to just before timer fires
+      jest.advanceTimersByTime(499);
+
+      // Stop now (timer is about to fire in 1ms)
+      await service.stop();
+
+      // Fire the timer (it's already in the event loop queue)
+      jest.advanceTimersByTime(1);
+      await Promise.resolve();
+
+      // Translation should NOT occur - the timer callback should check watch state
+      expect(mockFileTranslationService.translateFile).not.toHaveBeenCalled();
+
+      jest.useRealTimers();
+    });
+
+    it('should not throw errors if timer callback executes after stop', async () => {
+      jest.useFakeTimers();
+
+      const service = new WatchService(mockFileTranslationService, {
+        debounceMs: 300,
+      });
+
+      const testFile = path.join(testDir, 'test.txt');
+      fs.writeFileSync(testFile, 'Hello');
+
+      const options = {
+        targetLangs: ['es' as const],
+        outputDir: path.join(testDir, 'output'),
+      };
+
+      await service.watch(testDir, options);
+      service.handleFileChange(testFile);
+      await service.stop();
+
+      // Should not throw when timer fires after stop
+      expect(() => {
+        jest.advanceTimersByTime(300);
+      }).not.toThrow();
+
+      jest.useRealTimers();
+    });
+  });
 });

tests/unit/translate-command.test.ts

@@ -1355,4 +1355,157 @@ describe('TranslateCommand', () => {
       expect(mockFs.readFileSync).toHaveBeenCalledWith('/path/to/unicode.txt', 'utf-8');
     });
   });
+
+  describe('isFilePath() - cross-platform path detection (Issue #4)', () => {
+    it('should detect Windows paths with backslashes (C:\\Users\\file.txt)', async () => {
+      const fs = jest.requireActual('fs');
+      jest.spyOn(fs, 'existsSync').mockReturnValue(false);
+
+      // Access the private isFilePath method via translate()
+      // Windows path should be detected as file path
+      const spy = jest.spyOn(translateCommand as any, 'translateFile')
+        .mockResolvedValue('File translation result');
+
+      // Mock fileTranslationService.isSupportedFile to return true for .txt
+      const mockFileService = (translateCommand as any).fileTranslationService;
+      jest.spyOn(mockFileService, 'isSupportedFile').mockReturnValue(true);
+
+      await translateCommand.translate('C:\\Users\\Documents\\file.txt', {
+        to: 'es',
+        output: '/out.txt',
+      });
+
+      expect(spy).toHaveBeenCalledWith('C:\\Users\\Documents\\file.txt', { to: 'es', output: '/out.txt' });
+      spy.mockRestore();
+    });
+
+    it('should detect Unix paths with forward slashes (/home/user/file.txt)', async () => {
+      const fs = jest.requireActual('fs');
+      jest.spyOn(fs, 'existsSync').mockReturnValue(false);
+
+      const spy = jest.spyOn(translateCommand as any, 'translateFile')
+        .mockResolvedValue('File translation result');
+
+      const mockFileService = (translateCommand as any).fileTranslationService;
+      jest.spyOn(mockFileService, 'isSupportedFile').mockReturnValue(true);
+
+      await translateCommand.translate('/home/user/documents/file.txt', {
+        to: 'es',
+        output: '/out.txt',
+      });
+
+      expect(spy).toHaveBeenCalledWith('/home/user/documents/file.txt', { to: 'es', output: '/out.txt' });
+      spy.mockRestore();
+    });
+
+    it('should NOT treat URLs as file paths (http://example.com/file.txt)', async () => {
+      const fs = jest.requireActual('fs');
+      jest.spyOn(fs, 'existsSync').mockReturnValue(false);
+
+      const mockFileService = (translateCommand as any).fileTranslationService;
+      jest.spyOn(mockFileService, 'isSupportedFile').mockReturnValue(true);
+
+      (mockTranslationService.translate as jest.Mock).mockResolvedValueOnce({
+        text: 'Texto traducido',
+      });
+
+      // URL should be treated as text, not file path
+      await translateCommand.translate('http://example.com/file.txt', {
+        to: 'es',
+      });
+
+      // Should call translateText, NOT translateFile
+      expect(mockTranslationService.translate).toHaveBeenCalledWith(
+        'http://example.com/file.txt',
+        expect.any(Object),
+        expect.any(Object)
+      );
+    });
+
+    it('should NOT treat text containing "/" as file path', async () => {
+      const fs = jest.requireActual('fs');
+      jest.spyOn(fs, 'existsSync').mockReturnValue(false);
+
+      const mockFileService = (translateCommand as any).fileTranslationService;
+      jest.spyOn(mockFileService, 'isSupportedFile').mockReturnValue(false);
+
+      (mockTranslationService.translate as jest.Mock).mockResolvedValueOnce({
+        text: 'Texto traducido',
+      });
+
+      // Text with / should be treated as text, not file path
+      await translateCommand.translate('Check https://example.com for details', {
+        to: 'es',
+      });
+
+      // Should call translateText, NOT translateFile
+      expect(mockTranslationService.translate).toHaveBeenCalledWith(
+        'Check https://example.com for details',
+        expect.any(Object),
+        expect.any(Object)
+      );
+    });
+
+    it('should detect relative Windows paths (folder\\file.txt)', async () => {
+      const fs = jest.requireActual('fs');
+      jest.spyOn(fs, 'existsSync').mockReturnValue(false);
+
+      const spy = jest.spyOn(translateCommand as any, 'translateFile')
+        .mockResolvedValue('File translation result');
+
+      const mockFileService = (translateCommand as any).fileTranslationService;
+      jest.spyOn(mockFileService, 'isSupportedFile').mockReturnValue(true);
+
+      await translateCommand.translate('folder\\subfolder\\file.txt', {
+        to: 'es',
+        output: '/out.txt',
+      });
+
+      expect(spy).toHaveBeenCalledWith('folder\\subfolder\\file.txt', { to: 'es', output: '/out.txt' });
+      spy.mockRestore();
+    });
+
+    it('should detect relative Unix paths (folder/file.txt)', async () => {
+      const fs = jest.requireActual('fs');
+      jest.spyOn(fs, 'existsSync').mockReturnValue(false);
+
+      const spy = jest.spyOn(translateCommand as any, 'translateFile')
+        .mockResolvedValue('File translation result');
+
+      const mockFileService = (translateCommand as any).fileTranslationService;
+      jest.spyOn(mockFileService, 'isSupportedFile').mockReturnValue(true);
+
+      await translateCommand.translate('folder/subfolder/file.txt', {
+        to: 'es',
+        output: '/out.txt',
+      });
+
+      expect(spy).toHaveBeenCalledWith('folder/subfolder/file.txt', { to: 'es', output: '/out.txt' });
+      spy.mockRestore();
+    });
+
+    it('should handle files with no path separator (file.txt) as text when file doesn\'t exist', async () => {
+      const fs = jest.requireActual('fs');
+      jest.spyOn(fs, 'existsSync').mockReturnValue(false);
+
+      const mockFileService = (translateCommand as any).fileTranslationService;
+      jest.spyOn(mockFileService, 'isSupportedFile').mockReturnValue(true);
+
+      (mockTranslationService.translate as jest.Mock).mockResolvedValueOnce({
+        text: 'archivo.txt',
+      });
+
+      // No path separator and file doesn't exist -> treat as text
+      await translateCommand.translate('file.txt', {
+        to: 'es',
+      });
+
+      // Should call translateText, NOT translateFile
+      expect(mockTranslationService.translate).toHaveBeenCalledWith(
+        'file.txt',
+        expect.any(Object),
+        expect.any(Object)
+      );
+    });
+  });
 });