fix: address review — encode refs, handle GitHub auth errors, test no-ref path

- encode ref in GitHub/Gitea archive URLs (preserve slashes for nested branches)
- map GitHub 401/403 to a clear access-denied error
- document the opt-in @throws on the base getRepositoryPresignedUrl
- test the Gitea default-branch resolution (no-ref) path

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

Author: loks0n

src/VCS/Adapter.php

@@ -377,6 +377,8 @@ abstract public function getLatestCommit(string $owner, string $repositoryName,
      * @param  string  $ref Branch, tag or commit to download (defaults to the default branch)
      * @param  string  $format Archive format, e.g. 'tarball' or 'zipball'
      * @return string Presigned download URL
+     *
+     * @throws Exception when the adapter does not implement it (opt-in, mirrors createCheckRun())
      */
     public function getRepositoryPresignedUrl(string $owner, string $repositoryName, string $ref = '', string $format = 'tarball'): string
     {

src/VCS/Adapter/Git/GitHub.php

@@ -892,7 +892,8 @@ public function getRepositoryPresignedUrl(string $owner, string $repositoryName,
 
         $url = "/repos/$owner/$repositoryName/$format";
         if (!empty($ref)) {
-            $url .= "/$ref";
+            // Encode the ref but keep slashes so nested branch names (e.g. feature/foo) still resolve
+            $url .= '/' . \str_replace('%2F', '/', \rawurlencode($ref));
         }
 
         $response = $this->call(self::METHOD_GET, $url, ['Authorization' => "Bearer $this->accessToken"], [], false, false);
@@ -902,6 +903,9 @@ public function getRepositoryPresignedUrl(string $owner, string $repositoryName,
         if ($responseHeadersStatusCode === 404) {
             throw new RepositoryNotFound("Repository or ref not found.");
         }
+        if ($responseHeadersStatusCode === 401 || $responseHeadersStatusCode === 403) {
+            throw new Exception("Access denied to repository archive; check the access token and its permissions.", $responseHeadersStatusCode);
+        }
 
         $presignedUrl = $responseHeaders['location'] ?? '';
         if (empty($presignedUrl)) {

src/VCS/Adapter/Git/Gitea.php

@@ -290,7 +290,10 @@ public function getRepositoryPresignedUrl(string $owner, string $repositoryName,
             }
         }
 
-        return "{$this->endpoint}/repos/{$owner}/{$repositoryName}/archive/{$ref}.{$extension}?token=" . urlencode($this->accessToken);
+        // Encode the ref but keep slashes so nested branch names (e.g. feature/foo) still resolve
+        $encodedRef = \str_replace('%2F', '/', \rawurlencode($ref));
+
+        return "{$this->endpoint}/repos/{$owner}/{$repositoryName}/archive/{$encodedRef}.{$extension}?token=" . urlencode($this->accessToken);
     }
 
     public function getRepositoryName(string $repositoryId): string

tests/VCS/Adapter/GiteaTest.php

@@ -91,6 +91,16 @@ public function testGetRepositoryPresignedUrl(): void
         $zip = $adapter->getRepositoryPresignedUrl($owner, 'some-repo', static::$defaultBranch, 'zipball');
         $this->assertStringContainsString('.zip?token=', $zip);
 
+        // No ref: the default branch is resolved from the repository
+        $repositoryName = 'test-presigned-url-' . \uniqid();
+        $adapter->createRepository($owner, $repositoryName, false);
+        try {
+            $noRef = $adapter->getRepositoryPresignedUrl($owner, $repositoryName);
+            $this->assertStringContainsString("/archive/" . static::$defaultBranch . '.tar.gz?token=', $noRef);
+        } finally {
+            $adapter->deleteRepository($owner, $repositoryName);
+        }
+
         $this->expectException(\Exception::class);
         $adapter->getRepositoryPresignedUrl($owner, 'some-repo', static::$defaultBranch, 'invalid');
     }