✨ feat: add asset URL resolution for GitHub uploads (#1569)

* ✨ feat: add asset URL resolution for GitHub uploads

Introduced asset URL resolution in GitHubClient's API interface.

* ✨ Add asset URL resolution and corresponding tests
Added `resolveAssetUrl` to fetch short-lived URLs for GitHub assets.

* ✨: Enhance GitHub asset URL handling

Added regex matching for GitHub asset URLs and improved its resolution.

* 🐛 Fix asset URL resolution and validation in tests

Ensure asset URLs are correctly resolved and types validated.

Author: pelikhan

docs/src/content/docs/reference/scripts/github.mdx

@@ -126,6 +126,19 @@ const files = await github.downloadArtifact(artifact.id)
 console.log(files)
 ```
 
+### Assets
+
+Image or video assets urls uploaded through the GitHub UI can be resolved using `resolveAssetUrl`.
+They are typically of the form `https://github.com/.../assets/<uuid>`. The function returns a short lived URL with an embedded
+access token to download the asset.
+
+```js
+const url = await github.resolveAssetUrl(
+    "https://github.com/user-attachments/assets/a6e1935a-868e-4cca-9531-ad0ccdb9eace"
+)
+console.log(url)
+```
+
 ### Search Code
 
 Use `searchCode` for a code search on the default branch in the same repository.

packages/core/src/constants.ts

@@ -456,4 +456,6 @@ export const BOX_UP_AND_RIGHT = "╰"
 export const BOX_UP_AND_DOWN = "│"
 export const BOX_DOWN_UP_AND_RIGHT = "├"
 export const BOX_LEFT_AND_DOWN = "╮"
-export const BOX_LEFT_AND_UP = "╯"
+export const BOX_LEFT_AND_UP = "╯"
+
+export const GITHUB_ASSET_URL_RX = /^https:\/\/github\.com\/.*\/assets\/.*$/i

packages/core/src/githubclient.test.ts

@@ -5,6 +5,8 @@ import { readFile } from "node:fs/promises"
 import { fileURLToPath } from "node:url"
 import { isCI } from "./ci"
 import { TestHost } from "./testhost"
+import { resolveBufferLike } from "./bufferlike"
+import { tryResolveResource } from "./resources"
 
 describe("GitHubClient", async () => {
     const client = GitHubClient.default()
@@ -110,4 +112,26 @@ describe("GitHubClient", async () => {
         const un = await client.uploadAsset(undefined)
         assert(un === undefined)
     })
+    await test("resolveAssetUrl -image", async () => {
+        const resolved = await client.resolveAssetUrl(
+            "https://github.com/user-attachments/assets/a6e1935a-868e-4cca-9531-ad0ccdb9eace"
+        )
+        assert(resolved)
+        assert(resolved.includes("githubusercontent.com"))
+    })
+    await test("resolveAssetUrl - mp4", async () => {
+        const resolved = await client.resolveAssetUrl(
+            "https://github.com/user-attachments/assets/f7881bef-931d-4f76-8f63-b4d12b1f021e"
+        )
+        console.log(resolved)
+        assert(resolved.includes("githubusercontent.com"))
+    })
+
+    await test("resolveAssetUrl - image - indirect", async () => {
+        const resolved = await tryResolveResource(
+            "https://github.com/user-attachments/assets/a6e1935a-868e-4cca-9531-ad0ccdb9eace"
+        )
+        assert(resolved.files[0].content)
+        assert.strictEqual(resolved.files[0].type, "image/jpeg")
+    })
 })

packages/core/src/githubclient.ts

@@ -3,6 +3,7 @@ import type { PaginateInterface } from "@octokit/plugin-paginate-rest"
 import {
     GITHUB_API_VERSION,
     GITHUB_ASSET_BRANCH,
+    GITHUB_ASSET_URL_RX,
     GITHUB_PULL_REQUEST_REVIEW_COMMENT_LINE_DISTANCE,
     GITHUB_REST_API_CONCURRENCY_LIMIT,
     GITHUB_REST_PAGE_DEFAULT,
@@ -32,6 +33,7 @@ import { CancellationOptions, checkCancelled } from "./cancellation"
 import { diagnosticToGitHubMarkdown } from "./annotations"
 import { TraceOptions } from "./trace"
 import { unzip } from "./zip"
+import { uriRedact, uriTryParse } from "./url"
 const dbg = genaiscriptDebug("github")
 
 export interface GithubConnectionInfo {
@@ -1342,6 +1344,26 @@ export class GitHubClient implements GitHub {
         return data
     }
 
+    async resolveAssetUrl(url: string) {
+        if (!uriTryParse(url)) return undefined // unknown format
+        if (!GITHUB_ASSET_URL_RX.test(url)) return undefined // not a github asset
+        const { client, owner, repo } = await this.api()
+        dbg(`asset: resolving url for %s`, uriRedact(url))
+        const { data, status } = await client.rest.markdown.render({
+            owner,
+            repo,
+            context: `${owner}/${repo}`, // force html with token
+            text: `![](${url})`,
+            mode: "gfm",
+        })
+        dbg(`asset: resolution %s`, status)
+        const { resolved } =
+            /<img src="(?<resolved>[^"]+)"/i.exec(data)?.groups || {}
+        if (!resolved) dbg(`markdown:\n%s`, data)
+
+        return resolved
+    }
+
     async downloadArtifactFiles(
         artifactId: number | string
     ): Promise<WorkspaceFile[]> {

packages/core/src/resources.ts

@@ -12,14 +12,15 @@ import { GitClient } from "./git"
 import { expandFiles } from "./fs"
 import { join } from "node:path"
 import { isCancelError } from "./error"
+import { GITHUB_ASSET_URL_RX } from "./constants"
 const dbg = genaiscriptDebug("res")
 const dbgAdaptors = dbg.extend("adaptors")
 const dbgFiles = dbg.extend("files")
 dbgFiles.enabled = false
 
 const urlAdapters: {
     id: string
-    matcher: (url: string) => string
+    matcher: (url: string) => Awaitable<string>
 }[] = [
     {
         id: "github blob",
@@ -40,6 +41,17 @@ const urlAdapters: {
                 : undefined
         },
     },
+    {
+        id: "github assets",
+        matcher: async (url) => {
+            if (GITHUB_ASSET_URL_RX.test(url)) {
+                const client = GitHubClient.default()
+                const resolved = await client.resolveAssetUrl(url)
+                return resolved
+            }
+            return undefined
+        },
+    },
     {
         id: "gist",
         matcher: (url) => {
@@ -54,10 +66,10 @@ const urlAdapters: {
     },
 ]
 
-function applyUrlAdapters(url: string) {
+async function applyUrlAdapters(url: string) {
     // Use URL adapters to modify the URL if needed
     for (const a of urlAdapters) {
-        const newUrl = a.matcher(url)
+        const newUrl = await a.matcher(url)
         if (newUrl) {
             dbgAdaptors(`%s: %s`, a.id, uriRedact(url))
             return newUrl
@@ -83,7 +95,6 @@ const uriResolvers: Record<
         // https://.../.../....git
         if (/\.git($|\/)/.test(url.pathname))
             return await uriResolvers.git(dbg, url, options)
-
         // regular fetch
         const fetch = await createFetch(options)
         dbg(`fetch %s`, uriRedact(url.href))
@@ -211,7 +222,7 @@ export async function tryResolveResource(
     options?: TraceOptions & CancellationOptions
 ): Promise<{ uri: URL; files: WorkspaceFile[] } | undefined> {
     if (!url) return undefined
-    url = applyUrlAdapters(url)
+    url = await applyUrlAdapters(url)
     const uri = uriTryParse(url)
     if (!uri) return undefined
     const { cancellationToken } = options || {}

packages/core/src/types/prompt_template.d.ts

@@ -3870,6 +3870,11 @@ interface GitHub {
         }
     ): Promise<string>
 
+    /**
+     * Resolves user uploaded assets to a short lived URL with access token. Returns undefined if the asset is not found.
+     */
+    resolveAssetUrl(url: string): Promise<string | undefined>
+
     /**
      * Gets the underlying Octokit client
      */