[BUG] : Local setup, startup, and testing shell scripts fail on Windows Git Bash (MINGW64)

[omnipotentchaos]

Summary

When setting up and starting the SecuScan development environment on native Windows using Git Bash (MINGW64), the ./setup.sh and ./start.sh shell scripts fail immediately. This is caused by hardcoded Unix-specific virtual environment directory structures (venv/bin instead of venv/Scripts), a lack of the lsof command on Windows, and attempting to invoke python3 inside the active virtual environment where only python is present.

Why this matters

The docs/windows_contributor_guide.md explicitly recommends that Windows contributors run ./setup.sh and ./start.sh from Git Bash. Because these scripts crash immediately on fresh Windows Git Bash installations, it creates a high barrier to entry for new Windows contributors who cannot boot the local development environment out of the box.

Reproduction steps

List the exact steps needed to reproduce the behavior:

1. Open a native Windows system with Git Bash (MINGW64), Python 3.11+, Node.js, and npm installed.
2. Clone the repository and navigate to the directory: git clone https://github.com/utksh1/SecuScan.git && cd SecuScan
3. Run ./setup.sh in Git Bash. Observe the crash at line 151.
4. Run ./start.sh in Git Bash. Observe the crash at line 29.

Expected behavior

The ./setup.sh script should successfully build the virtual environment and install backend/frontend dependencies on Windows Git Bash. The ./start.sh script should successfully clean any lingering processes on ports 8000/5173 (using Windows tools like netstat and taskkill if lsof is absent) and start the backend and frontend dev servers.

Actual behavior

1. In ./setup.sh:
   The script fails to activate the virtual environment because it looks for venv/bin/activate or tries to source venv/Scripts/activate.bat (which fails in Git Bash with @echo: command not found).
2. In ./start.sh:
   The script crashes because it tries to run lsof which is missing:

   ./start.sh: line 29: lsof: command not found
   

   If that is bypassed, it fails when calling python3 -m uvicorn ... because Windows virtual environments do not contain a python3 executable (only python.exe), causing Git Bash to resolve to the system's global python3 binary instead of the active venv.

Scope

• Suggested files or directories: setup.sh, start.sh, testing/test_python.sh
• Related route, page, component, or script: Onboarding/Setup Scripts

Evidence

Error when sourcing .bat in Git Bash during setup:

venv/Scripts/activate.bat: line 1: @echo: command not found

Error when starting dev server:

🧹 Cleaning up existing processes on port 8000 and 5173...
./start.sh: line 29: lsof: command not found

Environment

• OS: Windows 10/11 (Native, using MINGW64 Git Bash)
• Python Version: 3.13.14 (or any 3.11+)
• Node Version: v24.14.0 (or any 18+)
• Docker Version: 29.2.0

Definition of done

• Bug is reproducible from the issue description
• Root cause is fixed (add dynamic detection of venv/Scripts vs venv/bin, fallback to netstat/taskkill when lsof is absent, and call python instead of python3 inside the active virtualenv)
• Relevant tests (such as testing/test_python.sh) are updated to handle the Windows path layout
• Docs are verified to ensure instructions in windows_contributor_guide.md align with the fixes

Additional context

Proposed Fixes

1. Dynamic Virtualenv Directory Helper (in setup/startup/test scripts)

if [ -d "venv/Scripts" ]; then
    VENV_BIN="venv/Scripts"
else
    VENV_BIN="venv/bin"
fi

# Activate cleanly on all platforms
source "$VENV_BIN/activate"

2. Cross-Platform Port Cleanup (in start.sh)

echo "🧹 Cleaning up existing processes on port 8000 and 5173..."
if command -v lsof &>/dev/null; then
  lsof -ti :8000 | xargs kill -9 2>/dev/null || true
  lsof -ti :5173 | xargs kill -9 2>/dev/null || true
elif command -v netstat &>/dev/null && command -v taskkill &>/dev/null; then
  for port in 8000 5173; do
    pids=$(netstat -ano | grep -i LISTENING | grep -E "[:.]$port[[:space:]]" | awk '{print $5}' | tr -d '\r' | sort -u || true)
    for pid in $pids; do
      if [ -n "$pid" ] && [[ "$pid" =~ ^[0-9]+$ ]]; then
        taskkill //F //PID "$pid" &>/dev/null || true
      fi
    done
  done
fi

[omnipotentchaos]

Please assign to me under GSSOC 2026.

[aaniya22]

pls assign this to me under gssoc

[utksh1]

Thanks—this is clear and actionable. Quick clarification: should the acceptance criteria explicitly include both venv/Scripts and venv/bin layouts under Windows Git Bash (MINGW64), and require that ./setup.sh/./start.sh succeed from a fresh clone with no manual edits?

[tmdeveloper007]

This issue has been open for a while with no recent activity or linked PR. Closing as stale. Feel free to reopen if this is still relevant.

[omnipotentchaos]

@tmdeveloper007 I have already linked PR #1630 in this linked.