[#2162] Added repository and reference existence validation.

- Added validateRemoteRepositoryExists() to verify remote repositories are accessible
- Added validateRemoteRefExists() to verify remote refs exist via HEAD requests
- Added validateLocalRepositoryExists() to verify local paths are valid git repositories
- Added validateLocalRefExists() to verify local refs exist using git rev-parse
- Validation occurs before download attempts for better error messaging
- Updated tests to expect new validation error messages
- Special refs (stable, HEAD) skip reference validation as they are auto-discovered

Author: AlexSkrypnyk

.vortex/installer/src/Downloader/RepositoryDownloader.php

@@ -161,6 +161,9 @@ protected function downloadFromRemote(string $repo, string $ref, ?string $destin
     }
     $repo_url = str_ends_with($repo, '.git') ? substr($repo, 0, -4) : $repo;
 
+    // Validate repository exists before proceeding.
+    $this->validateRemoteRepositoryExists($repo_url);
+
     $version = $ref;
     if ($ref === RepositoryDownloader::REF_STABLE) {
       $ref = $this->discoverLatestReleaseRemote($repo_url);
@@ -174,6 +177,10 @@ protected function downloadFromRemote(string $repo, string $ref, ?string $destin
     elseif ($ref === RepositoryDownloader::REF_HEAD) {
       $version = 'develop';
     }
+    else {
+      // Validate ref exists for non-special refs.
+      $this->validateRemoteRefExists($repo_url, $ref);
+    }
 
     $url = sprintf('%s/archive/%s.tar.gz', $repo_url, $ref);
 
@@ -190,6 +197,9 @@ protected function downloadFromLocal(string $repo, string $ref, ?string $destina
       throw new \InvalidArgumentException('Destination cannot be null for local downloads.');
     }
 
+    // Validate local repository exists.
+    $this->validateLocalRepositoryExists($repo);
+
     $ref = $ref === RepositoryDownloader::REF_STABLE ? RepositoryDownloader::REF_HEAD : $ref;
     $version = $ref;
 
@@ -200,6 +210,10 @@ protected function downloadFromLocal(string $repo, string $ref, ?string $destina
       $ref = $this->git->getLastShortCommitId();
       $version = 'develop';
     }
+    else {
+      // Validate ref exists for non-HEAD refs.
+      $this->validateLocalRefExists($repo, $ref);
+    }
 
     $archive_path = $this->archiveFromLocal($repo, $ref);
     $this->archiver->validate($archive_path);
@@ -329,4 +343,116 @@ protected function archiveFromLocal(string $repo, string $ref): string {
     return $temp_file;
   }
 
+  /**
+   * Validate that a remote repository exists and is accessible.
+   *
+   * @param string $repo_url
+   *   The repository URL (without .git extension).
+   *
+   * @throws \RuntimeException
+   *   If the repository is not accessible.
+   */
+  protected function validateRemoteRepositoryExists(string $repo_url): void {
+    $headers = ['User-Agent' => 'Vortex-Installer'];
+
+    $github_token = Env::get('GITHUB_TOKEN');
+    if ($github_token) {
+      $headers['Authorization'] = sprintf('Bearer %s', $github_token);
+    }
+
+    try {
+      // Try to access the repository root to verify it exists.
+      $response = $this->httpClient->request('HEAD', $repo_url, ['headers' => $headers, 'http_errors' => FALSE]);
+      $status_code = $response->getStatusCode();
+
+      if ($status_code >= 400) {
+        throw new \RuntimeException(sprintf('Repository not found or not accessible: "%s" (HTTP %d)', $repo_url, $status_code));
+      }
+    }
+    catch (RequestException $e) {
+      throw new \RuntimeException(sprintf('Unable to access repository: "%s" - %s', $repo_url, $e->getMessage()), $e->getCode(), $e);
+    }
+  }
+
+  /**
+   * Validate that a reference exists in a remote repository.
+   *
+   * @param string $repo_url
+   *   The repository URL (without .git extension).
+   * @param string $ref
+   *   The git reference to validate.
+   *
+   * @throws \RuntimeException
+   *   If the reference does not exist.
+   */
+  protected function validateRemoteRefExists(string $repo_url, string $ref): void {
+    $archive_url = sprintf('%s/archive/%s.tar.gz', $repo_url, $ref);
+    $headers = ['User-Agent' => 'Vortex-Installer'];
+
+    $github_token = Env::get('GITHUB_TOKEN');
+    if ($github_token) {
+      $headers['Authorization'] = sprintf('Bearer %s', $github_token);
+    }
+
+    try {
+      // Use HEAD request to check if the archive URL exists without downloading.
+      $response = $this->httpClient->request('HEAD', $archive_url, ['headers' => $headers, 'http_errors' => FALSE]);
+      $status_code = $response->getStatusCode();
+
+      if ($status_code === 404) {
+        throw new \RuntimeException(sprintf('Reference "%s" not found in repository "%s"', $ref, $repo_url));
+      }
+      elseif ($status_code >= 400) {
+        throw new \RuntimeException(sprintf('Unable to verify reference "%s" in repository "%s" (HTTP %d)', $ref, $repo_url, $status_code));
+      }
+    }
+    catch (RequestException $e) {
+      throw new \RuntimeException(sprintf('Unable to verify reference "%s" in repository "%s" - %s', $ref, $repo_url, $e->getMessage()), $e->getCode(), $e);
+    }
+  }
+
+  /**
+   * Validate that a local repository exists and is a valid git repository.
+   *
+   * @param string $repo
+   *   The local repository path.
+   *
+   * @throws \RuntimeException
+   *   If the repository does not exist or is not a valid git repository.
+   */
+  protected function validateLocalRepositoryExists(string $repo): void {
+    if (!is_dir($repo)) {
+      throw new \RuntimeException(sprintf('Local repository path does not exist: "%s"', $repo));
+    }
+
+    if (!is_dir($repo . '/.git')) {
+      throw new \RuntimeException(sprintf('Path is not a git repository: "%s"', $repo));
+    }
+  }
+
+  /**
+   * Validate that a reference exists in a local repository.
+   *
+   * @param string $repo
+   *   The local repository path.
+   * @param string $ref
+   *   The git reference to validate.
+   *
+   * @throws \RuntimeException
+   *   If the reference does not exist.
+   */
+  protected function validateLocalRefExists(string $repo, string $ref): void {
+    if (!$this->git instanceof Git) {
+      $this->git = new Git($repo);
+    }
+
+    try {
+      // Use git rev-parse to check if the ref exists.
+      $this->git->run('rev-parse', '--verify', $ref);
+    }
+    catch (\Exception $e) {
+      throw new \RuntimeException(sprintf('Reference "%s" not found in local repository "%s"', $ref, $repo), $e->getCode(), $e);
+    }
+  }
+
 }

.vortex/installer/tests/Unit/Downloader/RepositoryDownloaderTest.php

@@ -230,7 +230,7 @@ public function testArchiveFromLocalHandlesGitFailure(): void {
     exec('git commit -m "Initial commit" 2>&1');
     $downloader = new RepositoryDownloader();
     $this->expectException(\RuntimeException::class);
-    $this->expectExceptionMessage('Failed to create archive from local repository');
+    $this->expectExceptionMessage('Reference "nonexistent-ref" not found in local repository');
     $downloader->download($temp_repo_dir, 'nonexistent-ref', $temp_dest_dir);
   }
 
@@ -245,8 +245,8 @@ public function testDiscoverLatestReleaseRemoteWithGithubToken(): void {
     $mock_response->method('getBody')->willReturn($mock_body);
     $mock_body->method('getContents')->willReturn($release_json);
     $mock_response->method('getStatusCode')->willReturn(200);
-    // Only the API call uses httpClient now.
-    $mock_http_client->expects($this->once())->method('request')->willReturnCallback(function ($method, $url, array|\ArrayAccess $options) use ($mock_response): ResponseInterface {
+    // Two calls: HEAD for repo validation, GET for releases API.
+    $mock_http_client->expects($this->exactly(2))->method('request')->willReturnCallback(function ($method, $url, array|\ArrayAccess $options) use ($mock_response): ResponseInterface {
       $this->assertArrayHasKey('headers', $options);
       $this->assertArrayHasKey('Authorization', $options['headers']);
       $this->assertEquals('Bearer test_token_12345', $options['headers']['Authorization']);
@@ -826,7 +826,7 @@ public static function providerDiscoverLatestReleaseRemote(): array {
         'skipMockSetup' => FALSE,
         'expectedVersion' => NULL,
         'expectedException' => \RuntimeException::class,
-        'expectedMessage' => 'Unable to download release information from',
+        'expectedMessage' => 'Unable to access repository',
       ],
       'empty response' => [
         'repo' => 'https://github.com/user/repo',