Cross-Platform Compatibility

[behrangsa]

Summary

Ensure Samoid works correctly across Windows, macOS, and Linux operating systems with proper path handling and shell execution.

Acceptance Criteria

• AC7.1 Handle Windows vs Unix path separators correctly
• AC7.2 Support Windows command execution (cmd.exe vs sh)
• AC7.3 Handle file permissions appropriately per platform
• AC7.4 Support Windows Git Bash and WSL environments
• AC7.5 Test on all major platforms (Windows, macOS, Linux)
• AC7.6 Handle line ending differences (CRLF vs LF)

Details

AC7.1: Handle Windows vs Unix path separators correctly

Samoid must normalize all file system paths to use the appropriate separator for the current operating system. Specifically:

• When constructing paths, use std::path::Path and std::path::PathBuf which automatically handle platform-specific separators
• When joining paths, use Path::join() instead of string concatenation
• When displaying paths to users, use Path::display() which renders the correct separator
• When writing paths to Git configuration (via git config core.hooksPath), convert Windows backslashes to forward slashes as Git expects Unix-style paths even on Windows
• Example: The hooks directory .husky/_ must be written to Git config as .husky/_ on all platforms, not .husky\_ on Windows

AC7.2: Support Windows command execution (cmd.exe vs sh)

Samoid must execute hook scripts using the appropriate shell for each platform:

• Unix-like systems (Linux, macOS): Execute hooks using /bin/sh with the -e flag for error handling
• Windows without Git Bash: Execute hooks using cmd.exe /C
• Windows with Git Bash: Detect Git Bash availability and prefer sh.exe from Git installation
• Hook scripts must include appropriate shebang lines:
  • Unix: #!/usr/bin/env sh
  • Windows: Support both batch files (.bat, .cmd) and shell scripts
• Environment variable expansion must work correctly:
  • Unix: $HOME, $PATH, ${XDG_CONFIG_HOME}
  • Windows: %USERPROFILE%, %PATH%, %APPDATA%
• The PATH environment variable must be modified appropriately:
  • Prepend node_modules/.bin using platform-specific separator (: on Unix, ; on Windows)

AC7.3: Handle file permissions appropriately per platform

Samoid must set executable permissions on hook files according to platform capabilities:

• Unix-like systems: Set mode 0o755 (rwxr-xr-x) on all generated hook files using std::fs::set_permissions()
• Windows: File permissions are not required; Windows determines executability by file extension
• When creating the hooks directory and .gitignore file, use default permissions (no special mode required)
• Error handling: If permission setting fails on Windows, log a debug message but do not fail the operation

AC7.4: Support Windows Git Bash and WSL environments

Samoid must detect and properly support Unix-like environments running on Windows:

• Git Bash detection: Check for MSYSTEM environment variable (values: MINGW32, MINGW64, MSYS)
• WSL detection: Check for /proc/version containing "Microsoft" or "WSL"
• Cygwin detection: Check for CYGWIN environment variable
• When running in these environments:
  • Use Unix-style path separators
  • Execute hooks using sh instead of cmd.exe
  • Support Unix-style home directory resolution (~)
  • Handle path translation if needed (e.g., /c/Users → C:\Users)
• Configuration file locations:
  • Git Bash/MSYS2: Use $HOME/.config/samoid/init.sh
  • WSL: Use standard Linux paths
  • Native Windows: Use %APPDATA%\samoid\init.cmd or %USERPROFILE%\.config\samoid\init.sh if Git Bash is detected

AC7.5: Test on all major platforms (Windows, macOS, Linux)

Samoid must pass a comprehensive test suite on all supported platforms:

• CI/CD Matrix: Configure GitHub Actions to run tests on:
  • Ubuntu latest (Linux x86_64)
  • macOS latest (Darwin x86_64 and ARM64)
  • Windows latest (with and without Git Bash)
• Platform-specific tests: Include tests that verify:
  • Path separator handling
  • Shell execution differences
  • Permission setting behavior
  • Environment variable resolution
  • Home directory detection
• Integration tests: Test actual Git hook execution on each platform
• Performance benchmarks: Ensure no significant performance degradation on any platform

AC7.6: Handle line ending differences (CRLF vs LF)

Samoid must correctly handle text files with different line ending conventions:

• Generated files: Always write hook scripts with Unix line endings (LF) on all platforms, as both sh and Git Bash expect LF
• Reading configuration files: Accept both CRLF and LF when parsing:
  • .samoid.toml configuration files
  • User-provided hook scripts
  • Git configuration output
• Git integration: Respect the repository's core.autocrlf setting when creating files within the repository
• Error messages: When displaying file contents in error messages, normalize line endings to avoid confusing output
• Binary detection: Never modify line endings in binary files (detect using file extension or content analysis)

Priority: Medium

Effort: 6 story points
Phase: Construction

Source

Implied requirement from Husky's cross-platform support

Dependencies

• Depends on: Hook Execution Runtime #3 (Hook Execution Runtime)
• Relates to: Comprehensive Test Infrastructure #5 (Test Infrastructure), Robust Error Handling #6 (Error Handling)
• References: CI/CD Pipeline with GitHub Actions #11 (CI/CD Pipeline)

Cross-platform compatibility requires a fully functional runtime environment for proper validation. Comprehensive testing across all supported platforms must be integrated into the CI/CD pipeline to ensure consistent behavior and prevent platform-specific regressions.