Merge feature/cross-platform-ssh: v8.0.0 release

Cross-platform SSH support, module architecture, automated testing,
structured JSON output, and SemVer bug fixes.

Closes #15. Fixes #16.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: AndreaV-Lsi

.gitignore

@@ -5,8 +5,14 @@ LsiGitCheckout_Errors.txt
 # Repository directories
 repos/
 
-# User configuration files
-dependencies.json
+# Cloned test repositories (created by integration tests inside subdirectories)
+tests/*/test-root-*/
+tests/*/libs/
+tests/*/correlator-driver/
+
+# User configuration files (root only — test subdirectories have their own dependencies.json)
+/dependencies.json
+git_credentials.json
 
 # SSH keys
 *.ppk

CHANGELOG.md

@@ -5,20 +5,48 @@ All notable changes to LsiGitCheckout will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [8.0.0] - 2026-03-20
+## [8.0.0] - 2026-03-21
 
 ### Changed
+
 - **BREAKING**: Requires PowerShell 7.6 LTS or later (previously 5.1). PowerShell 7.6 installs side-by-side with Windows PowerShell 5.1.
 - Refactored monolithic script into module architecture: `LsiGitCheckout.psm1` (functions) + `LsiGitCheckout.ps1` (entry point)
 - Post-checkout scripts now execute via `pwsh` instead of `powershell.exe`
 - Replaced verbose null-check patterns with `??` null-coalescing operator
+- Entry point refactored to `try/catch/finally` pattern for guaranteed output file writing
+- Integration tests now perform actual git clones (no `-DryRun`) with full recursive checkout
+- Integration tests validate structured JSON output schema, not just exit codes
+- Integration tests clean up cloned repos between runs for test isolation
+- API incompatibility test configs now use `"Dependency File Name"` override for recursive lookup
 
 ### Added
+
+- **Cross-platform SSH support**: OpenSSH on macOS/Linux via `GIT_SSH_COMMAND`, PuTTY/plink on Windows
+  - `Test-SshTransportAvailable` replaces `Test-PlinkInstalled` (platform-aware)
+  - `Set-GitSshKeyOpenSsh` for Unix: validates key format, checks permissions, sets `GIT_SSH_COMMAND`
+  - `Set-GitSshKeyPlink` for Windows: existing PuTTY/Pageant logic (unchanged behavior)
+  - `Read-CredentialsFile` now warns about wrong key format for the current platform
 - `LsiGitCheckout.psm1` module file containing all function definitions
 - `LsiGitCheckout.psd1` module manifest
 - `Initialize-LsiGitCheckout` function for module state initialization
 - Automated unit tests using Pester 5.x (`tests/LsiGitCheckout.Unit.Tests.ps1`)
 - Automated integration tests for all 16 test configs (`tests/LsiGitCheckout.Integration.Tests.ps1`)
+- **Structured JSON output** via `-OutputFile` parameter for CI/CD pipeline integration
+  - Schema version 1.0.0 with execution metadata, per-repository results, summary counters, and error messages
+  - `Export-CheckoutResults` function generates the JSON output
+  - Output is guaranteed even on failure (written in `finally` block)
+- **Post-checkout script tracking** in JSON output per repository (`postCheckoutScript` field with configured, found, executed, status, reason) and at root level (`rootPostCheckoutScripts` array)
+- **`requestedBy` field** on each repository entry showing which parent repo or dependency file requested it
+- `Test-InteractiveSession` helper to detect non-interactive environments
+- Error message collector in `Write-Log` for structured output
+- `docs/test_repositories_reference.md` — catalog of all test repo tags and their dependencies
+
+### Fixed
+
+- **Show-ErrorDialog pipeline leakage**: `MessageBox::Show()` return value leaked to pipeline, causing failures to be counted as successes
+- **Non-interactive GUI dialogs**: `Show-ErrorDialog` and `Show-ConfirmDialog` now skip GUI in `pwsh -NonInteractive` and CI environments
+- **SemVer version parsing in DryRun**: added guard to skip parsing when repo is not cloned
+- **SemVer version resolution with `-DisableRecursion`** (#16): version resolution was gated behind `RecursiveMode`, causing empty tags when using `-DisableRecursion` with SemVer mode
 
 ## [7.1.0] - 2025-09-02
 

CLAUDE.md

@@ -11,9 +11,10 @@ PowerShell-based dependency management tool that checks out multiple Git reposit
 .\LsiGitCheckout.ps1 -InputFile "path/to/deps.json"     # custom config
 .\LsiGitCheckout.ps1 -DryRun                             # preview without executing
 .\LsiGitCheckout.ps1 -EnableDebug -EnableErrorContext     # full debug output
+.\LsiGitCheckout.ps1 -OutputFile result.json             # structured JSON output
 ```
 
-Key parameters: `-InputFile`, `-CredentialsFile`, `-DryRun`, `-EnableDebug`, `-DisableRecursion`, `-MaxDepth` (default 5), `-ApiCompatibility` (Strict|Permissive), `-DisablePostCheckoutScripts`, `-EnableErrorContext`
+Key parameters: `-InputFile`, `-CredentialsFile`, `-DryRun`, `-EnableDebug`, `-DisableRecursion`, `-MaxDepth` (default 5), `-ApiCompatibility` (Strict|Permissive), `-DisablePostCheckoutScripts`, `-EnableErrorContext`, `-OutputFile` (structured JSON results)
 
 ## Testing
 
@@ -32,13 +33,17 @@ Invoke-Pester ./tests/LsiGitCheckout.Integration.Tests.ps1 -Output Detailed
 
 ### Manual Testing
 
-Test configs in `tests/` can also be run manually:
+Test configs in `tests/` are organized in subdirectories, each containing a `dependencies.json`:
 
 ```powershell
-.\LsiGitCheckout.ps1 -InputFile tests/dependencies_semver.json -DryRun
+.\LsiGitCheckout.ps1 -InputFile tests/semver-basic/dependencies.json
+.\LsiGitCheckout.ps1 -InputFile tests/agnostic-recursive/dependencies.json
+.\LsiGitCheckout.ps1 -InputFile tests/api-incompatibility-agnostic/dependencies.json -ApiCompatibility Strict
 ```
 
-There are 16 test JSON configs covering SemVer, Agnostic, API incompatibility, custom paths, post-checkout scripts, and recursive dependencies.
+There are 17 test cases across 16 test configs covering SemVer, Agnostic, API incompatibility (Permissive + Strict), custom paths, post-checkout scripts, and recursive dependencies. See `docs/testing_infrastructure.md` for the full test architecture.
+
+**Important**: Integration tests depend on 5 external GitHub test repos. Modifying those repos will break the tests. See `docs/testing_infrastructure.md` for details.
 
 ## Architecture
 
@@ -48,8 +53,15 @@ There are 16 test JSON configs covering SemVer, Agnostic, API incompatibility, c
 - **Two dependency resolution modes**: SemVer (recommended, automatic version resolution) and Agnostic (explicit tag-based)
 - **Configuration**: JSON files — `dependencies.json` for repos, `git_credentials.json` for SSH keys
 - **Recursive processing**: walks dependency trees with conflict detection, max depth configurable
-- **SSH**: PuTTY/Pageant integration for authentication (`.ppk` key format)
+- **SSH**: Cross-platform — PuTTY/Pageant on Windows (`.ppk`), OpenSSH on macOS/Linux
 - **Post-checkout scripts**: optional PowerShell scripts run after successful checkouts
+- **Structured output**: `-OutputFile` writes JSON (schema 1.0.0) with per-repo results, post-checkout script tracking, and `requestedBy` parent chain
+
+## Design Decisions
+
+- **API compatibility in Agnostic mode**: In **Permissive** mode (default), version/tag conflicts during recursive checkout are resolved silently by picking the best available tag. In **Strict** mode, any tag mismatch is an error. This is controlled by `-ApiCompatibility` (CLI) or `"API Compatibility"` (per-repo JSON field).
+- **SemVer major version conflicts**: SemVer mode always rejects cross-major version incompatibilities regardless of the API compatibility setting, since different major versions imply breaking API changes by SemVer convention.
+- **SSH transport is platform-specific**: On Windows, PuTTY/plink with `.ppk` keys and Pageant is used. On macOS/Linux, OpenSSH is used via `GIT_SSH_COMMAND="ssh -i <key> -o IdentitiesOnly=yes"`, which specifies keys per-host without requiring `~/.ssh/config` changes or a running `ssh-agent`. **Why PuTTY on Windows**: We attempted OpenSSH on Windows but hit a specific failure: when a parent repository is cloned via HTTPS and has submodules accessed via SSH, the `git submodule update` process on Windows did not reliably inherit `GIT_SSH_COMMAND`/`GIT_SSH` environment variables, causing SSH submodule fetches to fail silently or hang. PuTTY/plink with Pageant (which manages keys via a system-tray agent process rather than environment variables) was the only reliable workaround. This issue was not reproduced on macOS/Linux, where environment variable inheritance across git subprocess forks works correctly.
 
 ## Coding Conventions
 
@@ -71,13 +83,18 @@ LsiGitCheckout.psd1      # Module manifest
 CHANGELOG.md             # Version history
 README.md                # Comprehensive user documentation
 docs/
-  developer_guide.md    # Developer setup, testing, debugging
-  comparison_guide.md    # vs Google Repo Tool
-  migration_guide.md     # Migration strategies
+  developer_guide.md            # Developer setup, testing, debugging
+  comparison_guide.md            # vs Google Repo Tool
+  migration_guide.md             # Migration strategies
+  test_repositories_reference.md # Test repo tags and dependency data
+  testing_infrastructure.md      # Test architecture, constraints, and categories
 examples/                # 7 example dependency JSON configs
-tests/                   # 16 test JSON configs + Pester test files
-  LsiGitCheckout.Unit.Tests.ps1         # Unit tests (no network)
-  LsiGitCheckout.Integration.Tests.ps1  # Integration tests (needs network)
+tests/                   # Pester test files + 16 test config subdirectories
+  LsiGitCheckout.Unit.Tests.ps1         # 65 unit tests (no network)
+  LsiGitCheckout.Integration.Tests.ps1  # 17 integration tests (needs network)
+  semver-basic/dependencies.json        # Test configs in subdirectories
+  agnostic-recursive/dependencies.json  # (16 subdirectories total)
+  api-incompatibility-*/dependencies.json
 ```
 
 ## Key Domain Concepts

LsiGitCheckout.ps1

@@ -84,12 +84,15 @@ param(
     [switch]$DisablePostCheckoutScripts,
 
     [Parameter()]
-    [switch]$EnableErrorContext
+    [switch]$EnableErrorContext,
+
+    [Parameter()]
+    [string]$OutputFile
 )
 
 # Import module from same directory as this script
 $scriptDir = Split-Path -Parent $MyInvocation.MyCommand.Path
-Import-Module (Join-Path $scriptDir 'LsiGitCheckout.psm1') -Force
+Import-Module (Join-Path $scriptDir 'LsiGitCheckout.psm1') -Force -DisableNameChecking
 
 # Initialize module state from script parameters
 Initialize-LsiGitCheckout `
@@ -100,9 +103,11 @@ Initialize-LsiGitCheckout `
     -MaxDepth $MaxDepth `
     -ApiCompatibility $ApiCompatibility `
     -DisablePostCheckoutScripts:$DisablePostCheckoutScripts `
-    -EnableErrorContext:$EnableErrorContext
+    -EnableErrorContext:$EnableErrorContext `
+    -OutputFile $OutputFile
 
 # Main execution
+$exitCode = 0
 try {
     Write-Log "LsiGitCheckout started - Version 8.0.0" -Level Info
     Write-Log "Script path: $scriptDir" -Level Debug
@@ -128,6 +133,10 @@ try {
         Write-Log "Error context: DISABLED - Use -EnableErrorContext for detailed error information" -Level Debug
     }
 
+    if ($OutputFile) {
+        Write-Log "Structured output will be written to: $OutputFile" -Level Info
+    }
+
     # Calculate and log script hash in debug mode
     if ($EnableDebug) {
         $scriptContent = Get-Content -Path $MyInvocation.MyCommand.Path -Raw
@@ -149,7 +158,7 @@ try {
 
     # Check Git installation
     if (-not (Test-GitInstalled)) {
-        exit 1
+        throw "Git is not installed or not accessible in PATH"
     }
 
     # Determine input file path
@@ -175,10 +184,7 @@ try {
 
     # Check if input file exists
     if (-not (Test-Path $InputFile)) {
-        $errorMessage = "Input file not found: $InputFile"
-        Write-Log $errorMessage -Level Error
-        Show-ErrorDialog -Message $errorMessage
-        exit 1
+        throw "Input file not found: $InputFile"
     }
 
     # Process the initial dependency file with enhanced error handling
@@ -236,19 +242,27 @@ try {
     # Show summary
     Show-Summary
 
-    # Get failure count from module
+    # Determine exit code from failure count
     $failureCount = & (Get-Module LsiGitCheckout) { $script:FailureCount }
-
-    # Exit with appropriate code
     if ($failureCount -gt 0) {
-        exit 1
-    }
-    else {
-        exit 0
+        $exitCode = 1
     }
 }
 catch {
     Write-ErrorWithContext -ErrorRecord $_ -AdditionalMessage "Unexpected error in main execution"
     Show-ErrorDialog -Message $_.Exception.Message
-    exit 1
+    $exitCode = 1
 }
+finally {
+    # Write structured output if requested — guaranteed even on failure
+    if (-not [string]::IsNullOrEmpty($OutputFile)) {
+        try {
+            Export-CheckoutResults -OutputFile $OutputFile
+        }
+        catch {
+            Write-Host "Failed to write output file: $_" -ForegroundColor Red
+        }
+    }
+}
+
+exit $exitCode

LsiGitCheckout.psd1

@@ -26,7 +26,7 @@
         'Show-ConfirmDialog',
         'Test-GitInstalled',
         'Test-GitLfsInstalled',
-        'Test-PlinkInstalled',
+        'Test-SshTransportAvailable',
         'Get-RepositoryUrl',
         'Get-HostnameFromUrl',
         'Get-SshKeyForUrl',
@@ -45,6 +45,8 @@
         'Process-DependencyFile',
         'Process-RecursiveDependencies',
         'Read-CredentialsFile',
+        'Set-PostCheckoutScriptResult',
+        'Export-CheckoutResults',
         'Show-Summary'
     )