What Happened
On Windows systems, running npm run win-dev starts the command but fails to launch the backend services. This causes the terminal to hang at “Waiting for servers to start” or fail without starting the required Python processes.
Problem
- The issue stemmed from missing platform-specific startup scripts in the source code repository.
The entry point, scripts/win-dev.bat, contains commands to specifically execute run.bat within the backend/ and sync-microservice/ directories.
- Root Cause: These
run.bat files were not present in the repository. While run.sh files existed for Linux/macOS users, the Windows equivalents were omitted.
- Result:
When win-dev.bat executed start "" /B run.bat, the command failed to locate the target file, resulting in the backend services never starting.
Expected Behavior
When a developer runs npm run win-dev on a Windows machine:
The script should locate and execute backend/run.bat to start the main Python backend.
The script should locate and execute sync-microservice/run.bat to start the synchronization service.
Both services should run in the background.
The frontend should launch and successfully connect to these running local services.
Suggestions for Prevention & Improvement
Immediately Actionable
Commit Missing Files:
Ensure both backend/run.bat and sync-microservice/run.bat are permanently added to the git repository so they are available for all future Windows users.
Long-Term Improvements
Robust Scripting:
Add explicit if exist checks in scripts/win-dev.bat. If run.bat is missing, the script should exit immediately with a helpful error message (e.g., Error: backend/run.bat not found) instead of failing silently.
Cross-Platform Task Running:
Consider replacing OS-specific shell scripts (.bat and .sh) with a platform-agnostic task runner (e.g., concurrently, nx, or a Node.js script).
CI/CD Verification:
Add a CI step to verify that all scripts referenced in package.json exist in the file system.
Record
What Happened
On Windows systems, running npm run win-dev starts the command but fails to launch the backend services. This causes the terminal to hang at “Waiting for servers to start” or fail without starting the required Python processes.
Problem
The entry point,
scripts/win-dev.bat, contains commands to specifically executerun.batwithin thebackend/andsync-microservice/directories.run.batfiles were not present in the repository. Whilerun.shfiles existed for Linux/macOS users, the Windows equivalents were omitted.When win-dev.bat executed
start "" /B run.bat, the command failed to locate the target file, resulting in the backend services never starting.Expected Behavior
When a developer runs
npm run win-devon a Windows machine:The script should locate and execute
backend/run.batto start the main Python backend.The script should locate and execute
sync-microservice/run.batto start the synchronization service.Both services should run in the background.
The frontend should launch and successfully connect to these running local services.
Suggestions for Prevention & Improvement
Immediately Actionable
Commit Missing Files:
Ensure both
backend/run.batandsync-microservice/run.batare permanently added to the git repository so they are available for all future Windows users.Long-Term Improvements
Robust Scripting:
Add explicit if exist checks in scripts/win-dev.bat. If run.bat is missing, the script should exit immediately with a helpful error message (e.g., Error: backend/run.bat not found) instead of failing silently.
Cross-Platform Task Running:
Consider replacing OS-specific shell scripts (.bat and .sh) with a platform-agnostic task runner (e.g., concurrently, nx, or a Node.js script).
CI/CD Verification:
Add a CI step to verify that all scripts referenced in package.json exist in the file system.
Record