[UPDATE PRIMITIVE] Cross-platform support for Windows compatibility

[Copilot]

📝 Update Information

Primitive Details

• Type: Infrastructure (multiple primitives affected)
• Name: Core server and CI infrastructure
• Update Category: Bug Fix / Cross-Platform Compatibility

⚠️ CRITICAL: PR SCOPE VALIDATION

✅ ALLOWED FILES:

• Server implementation files (server/src/**/*.ts)
• Modified supporting library files (server/src/lib/*.ts)
• Client implementation files (client/src/**/*.js)
• CI workflow files (.github/workflows/*.yml, .github/actions/**)
• Bundled output (server/dist/**)

🚫 FORBIDDEN FILES:

• No temporary or test output files
• No IDE configuration files
• No log files or debug output

---

🛑 MANDATORY PR VALIDATION CHECKLIST

• ONLY server implementation files are included
• NO temporary or output files are included
• NO unrelated configuration files are included
• ALL existing tests continue to pass
• NEW functionality is properly tested

---

• Impact Scope: Moderate - affects URI construction and path handling across server/client

Update Metadata

• Breaking Changes: No
• API Compatibility: Maintained
• Performance Impact: Neutral (minor improvement from replace() vs split/join)

🎯 Changes Description

Current Behavior

Three categories of cross-platform bugs:

1. file:// URIs constructed via string concatenation fail on Windows (backslashes, spaces)
2. __dirname.includes('src/lib') fails on Windows (src\lib)
3. .split('/').pop() fails on Windows paths

Updated Behavior

• pathToFileURL() handles URI encoding correctly on all platforms
• Path separator normalization before string matching
• path.basename() handles both separator types

Motivation

PR #18 revealed these patterns; this systematically audits and fixes them across the codebase.

🔄 Before vs. After Comparison

Functionality Changes

// BEFORE: Broken on Windows
if (import.meta.url === `file://${process.argv[1]}`) { ... }
const uri = `file://${resolve(cwd, 'ql')}`;
const fileName = queryPath.split('/').pop();

// AFTER: Cross-platform
if (import.meta.url === pathToFileURL(process.argv[1]).href) { ... }
const uri = pathToFileURL(resolve(cwd, 'ql')).href;
const fileName = basename(queryPath);

CI Workflow Changes

# BEFORE
runs-on: ubuntu-latest

# AFTER
strategy:
  matrix:
    os: [ubuntu-latest, windows-latest]
runs-on: ${{ matrix.os }}

🧪 Testing & Validation

Test Results

• Unit Tests: All pass (345/345 tests)
• Build: Passes on Ubuntu
• Manual Testing: Verified patterns eliminated via grep

📋 Implementation Details

Files Modified

• server/src/ql-mcp-server.ts - entrypoint detection
• server/src/tools/codeql/language-server-eval.ts - workspace URI
• server/src/lib/cli-tool-registry.ts - path normalization, basename() usage
• server/src/prompts/workflow-prompts.ts - workshop name derivation
• client/src/ql-mcp-client.js - entrypoint detection
• .github/workflows/client-integration-tests.yml - OS matrix, platform-specific cleanup
• .github/actions/setup-codeql-environment/action.yml - Windows cache paths

Code Changes Summary

• Error Handling: Proper URI encoding prevents malformed URIs
• Type Safety: Using Node.js url and path APIs correctly

Dependencies

• No New Dependencies: Uses existing node:url and node:path

🔗 References

Related Issues/PRs

• Related PRs: Security fixes for TOCTOU & OS tmp files #18 (Security fixes for TOCTOU & OS tmp files)

🚀 Compatibility & Migration

Backward Compatibility

• Fully Compatible: No breaking changes

API Evolution

• Maintained Contracts: Core API contracts preserved

👥 Review Guidelines

For Reviewers

• ⚠️ SCOPE COMPLIANCE: PR contains only server/client implementation files and CI
• ⚠️ NO UNRELATED FILES: Clean diff
• ⚠️ BACKWARD COMPATIBILITY: Existing functionality preserved

Testing Instructions

npm ci --workspaces
npm run build --workspace=server
npm test --workspace=server
npm run lint

📊 Impact Assessment

Server Impact

• Startup Time: No impact
• Runtime Stability: Improved on Windows
• Resource Usage: No change
• Concurrent Usage: Safe

🔄 Deployment Strategy

Rollout Considerations

• Safe Deployment: No breaking changes
• Monitoring: CI now validates both platforms

Original prompt

---

This section details on the original issue you should resolve

<issue_title>Verify and ensure cross-platform support (Windows vs macOS/Linux)</issue_title>
<issue_description>## Summary

PR #18 (Security fixes for TOCTOU & OS tmp files) introduced several cross-platform issues that were caught during code review. While those specific problems have been fixed, this issue tracks the broader effort to verify equivalent Windows support across the CodeQL Development MCP Server and prevent regressions through CI workflow improvements.

Background

The following categories of cross-platform bugs were found and fixed in PR #18:

Category	Example	Fix Applied
Invalid file URI construction	`file://${path}` produces broken URIs on Windows (backslashes, spaces)	Use pathToFileURL() from node:url
ESM __dirname unavailable	__dirname is not defined in ESM modules, would throw ReferenceError	Use fileURLToPath(import.meta.url) + dirname()
Hardcoded POSIX separators	getProjectTmpDir('quickeval') + '/quickeval.bqrs'	Use path.join()
POSIX-only path.includes()	__dirname.includes('src/utils') fails on Windows src\utils	Normalize separators before checking
POSIX-only split('/')	tempDir.split('/').pop() fails on Windows paths	Use path.basename()

These patterns may exist elsewhere in the codebase and should be systematically audited.

Goals

1. Code changes for Windows compatibility

• Audit all file:// URI construction across server/src/ and server/test/ — replace any string concatenation with pathToFileURL().
• Audit all uses of __dirname and __filename — ensure ESM-safe equivalents (fileURLToPath + dirname) are used consistently.
• Audit all path string manipulation — replace hardcoded / separators with path.join(), path.sep, or path.basename() as appropriate.
• Audit all string.includes() / string.split() calls on file paths — ensure they handle both \ and / separators.
• Verify client/src/ JavaScript files for the same patterns.

2. CI workflow improvements for multi-platform validation

• Update .github/workflows/client-integration-tests.yml to run on a matrix of windows-latest and ubuntu-latest runners for pushes and pull requests.
• Review other .github/workflows/*.yml workflows for opportunities to add Windows runner coverage.
• Ensure test setup steps (CodeQL CLI installation, database creation, etc.) work correctly on Windows runners.
• Add any Windows-specific environment configuration needed (e.g., path normalization, shell selection).

Acceptance Criteria

• All existing unit tests pass on both ubuntu-latest and windows-latest CI runners.
• All client integration tests pass on both ubuntu-latest and windows-latest CI runners.
• No remaining hardcoded POSIX path separators or file:// string concatenation in server source or test code.
  </issue_description>

Comments on the Issue (you are @copilot in this section)

Custom agent used: ql-mcp-tool-developer
An agent for developing new tools and/or improving existing tools for the QL MCP Server.

• Fixes Verify and ensure cross-platform support (Windows vs macOS/Linux) #19

---

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.

[data-douser]

Superseded by #22