@memberjunction/open-app-engine 6.2.0-edge.4 → 6.2.0-edge.6

package/dist/github/github-client.d.ts

@@ -31,13 +31,16 @@ export declare class GitHubAccessError extends Error {
     readonly Status: number;
     constructor(status: number, message: string);
 }
-export declare function FetchManifestFromGitHub(repoUrl: string, version: string | undefined, options: GitHubClientOptions, subpath?: string): Promise<ManifestFetchResult>;
+export declare function FetchManifestFromGitHub(repoUrl: string, version: string | undefined, options: GitHubClientOptions, subpath?: string, appName?: string): Promise<ManifestFetchResult>;
 export declare function ListGitHubReleases(repoUrl: string, options: GitHubClientOptions): Promise<GitHubRelease[]>;
-export declare function DownloadMigrations(repoUrl: string, version: string | undefined, migrationsPath: string, localDir: string, options: GitHubClientOptions, subpath?: string): Promise<MigrationDownloadResult>;
-export declare function GetLatestVersion(repoUrl: string, options: GitHubClientOptions, subpath?: string): Promise<string | null>;
-export declare function ListGitHubTags(repoUrl: string, options: GitHubClientOptions, subpath?: string): Promise<string[]>;
+export declare function ExtractSqlFilesFromTarGz(tarGzBuffer: Buffer, cleanPath: string, localDir: string): string[];
+export declare function DownloadMigrations(repoUrl: string, version: string | undefined, migrationsPath: string, localDir: string, options: GitHubClientOptions, subpath?: string, appName?: string): Promise<MigrationDownloadResult>;
+export declare function DescribeUnresolvedVersion(repoUrl: string, options: GitHubClientOptions, subpath?: string): Promise<string>;
+export declare function GetLatestVersion(repoUrl: string, options: GitHubClientOptions, subpath?: string, appName?: string): Promise<string | null>;
+export declare function FindVersionTagName(repoUrl: string, options: GitHubClientOptions, version: string, subpath?: string, appName?: string): Promise<string | null>;
+export declare function ListGitHubTags(repoUrl: string, options: GitHubClientOptions, subpath?: string, appName?: string): Promise<string[]>;
 export declare function ClearGitHubTagCache(): void;
-export declare function ValidateGitHubTag(repoUrl: string, version: string, options: GitHubClientOptions, subpath?: string): Promise<{
+export declare function ValidateGitHubTag(repoUrl: string, version: string, options: GitHubClientOptions, subpath?: string, appName?: string): Promise<{
     Exists: boolean;
     ErrorMessage?: string;
 }>;

package/dist/github/github-client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"github-client.d.ts","sourceRoot":"","sources":["../../src/github/github-client.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"github-client.d.ts","sourceRoot":"","sources":["../../src/github/github-client.ts"],"names":[],"mappings":"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"}

package/dist/github/github-client.js

@@ -1,29 +1,91 @@
 import { writeFileSync, mkdirSync, existsSync } from 'node:fs';
 import { join, dirname } from 'node:path';
+import { gunzipSync } from 'node:zlib';
 import { Octokit } from '@octokit/rest';
 import semver from 'semver';
+function trimSlashes(value) {
+    let start = 0;
+    let end = value.length;
+    while (start < end && value.charCodeAt(start) === 47)
+        start++;
+    while (end > start && value.charCodeAt(end - 1) === 47)
+        end--;
+    return value.slice(start, end);
+}
+function SubpathOrUndefined(value) {
+    return value === undefined ? undefined : trimSlashes(value);
+}
+function TrimLeadingSlashes(value) {
+    let start = 0;
+    while (start < value.length && value.charCodeAt(start) === 47) {
+        start++;
+    }
+    return value.slice(start);
+}
+function TrimSlashes(value) {
+    let start = 0;
+    let end = value.length;
+    while (start < end && value.charCodeAt(start) === 47) {
+        start++;
+    }
+    while (end > start && value.charCodeAt(end - 1) === 47) {
+        end--;
+    }
+    return value.slice(start, end);
+}
 export function ParseGitHubUrl(repoUrl) {
-    const match = repoUrl.match(/github\.com\/([^/?#]+)\/([^/?#]+)((?:\/[^?#]+)*)/);
-    if (!match) {
+    const hostIdx = repoUrl.indexOf('github.com/');
+    if (hostIdx < 0) {
+        return null;
+    }
+    const afterHost = repoUrl.slice(hostIdx + 'github.com/'.length);
+    let endIdx = afterHost.length;
+    const qIdx = afterHost.indexOf('?');
+    if (qIdx >= 0 && qIdx < endIdx)
+        endIdx = qIdx;
+    const hIdx = afterHost.indexOf('#');
+    if (hIdx >= 0 && hIdx < endIdx)
+        endIdx = hIdx;
+    const pathPart = TrimSlashes(afterHost.slice(0, endIdx));
+    const firstSlash = pathPart.indexOf('/');
+    if (firstSlash <= 0) {
+        return null;
+    }
+    const owner = pathPart.slice(0, firstSlash);
+    const remainder = pathPart.slice(firstSlash + 1);
+    const secondSlash = remainder.indexOf('/');
+    const rawRepo = secondSlash >= 0 ? remainder.slice(0, secondSlash) : remainder;
+    if (!rawRepo) {
+        return null;
+    }
+    const repo = rawRepo.endsWith('.git') ? rawRepo.slice(0, -4) : rawRepo;
+    if (!repo) {
         return null;
     }
-    const owner = match[1];
-    const repo = match[2].replace(/\.git$/, '');
-    const rawSubpath = (match[3] ?? '').replace(/^\/+|\/+$/g, '');
+    const rawSubpath = secondSlash >= 0 ? TrimSlashes(remainder.slice(secondSlash + 1)) : '';
     const subpath = rawSubpath.length > 0 ? rawSubpath : undefined;
     return { Owner: owner, Repo: repo, Subpath: subpath };
 }
 function ResolveToken(repoUrl, options) {
     if (options.TokenMap) {
+        const entries = Object.entries(options.TokenMap);
         const normalized = normalizeRepoUrl(repoUrl);
-        for (const [mapUrl, mapToken] of Object.entries(options.TokenMap)) {
-            if (normalizeRepoUrl(mapUrl) === normalized) {
-                return mapToken;
-            }
+        const exact = entries.find(([mapUrl]) => normalizeRepoUrl(mapUrl) === normalized);
+        if (exact) {
+            return exact[1];
+        }
+        const repoKey = repositoryKey(repoUrl);
+        const sameRepo = repoKey ? entries.find(([mapUrl]) => repositoryKey(mapUrl) === repoKey) : undefined;
+        if (sameRepo) {
+            return sameRepo[1];
         }
     }
     return options.Token;
 }
+function repositoryKey(url) {
+    const parsed = ParseGitHubUrl(url);
+    return parsed ? `${parsed.Owner}/${parsed.Repo}`.toLowerCase() : null;
+}
 function normalizeRepoUrl(url) {
     return url.replace(/\.git$/, '').replace(/\/$/, '').toLowerCase();
 }
@@ -84,6 +146,38 @@ function ThrowIfRateLimitedOrForbidden(error, context) {
             `This is NOT the same as "no versions found" — check your GitHub token and rate limit.`);
     }
 }
+async function ProbeRepoVisibility(repoUrl, parsed, options) {
+    try {
+        await CreateOctokit(repoUrl, options).repos.get({ owner: parsed.Owner, repo: parsed.Repo });
+        return { State: 'Readable' };
+    }
+    catch (error) {
+        if (OctokitStatus(error) === 404) {
+            return { State: 'NotReadable' };
+        }
+        return { State: 'Undetermined', Reason: error instanceof Error ? error.message : String(error) };
+    }
+}
+const CONFIGURE_CREDENTIAL_REMEDY = 'set GITHUB_TOKEN in the environment, or add the repo to openApps.github.tokens (or set openApps.github.token) in mj.config.cjs';
+function UnreadableRepoMessage(repoUrl, parsed, options) {
+    const target = `${parsed.Owner}/${parsed.Repo}`;
+    return ResolveToken(repoUrl, options)
+        ? `Cannot read ${target}. The repository does not exist, or the GitHub credential supplied does not grant access to it — check the token is valid and carries 'repo' scope for ${target}.`
+        : `Cannot read ${target}. The repository is private or does not exist, and no GitHub credential was supplied — ${CONFIGURE_CREDENTIAL_REMEDY}, then retry.`;
+}
+async function DescribeNotFound(repoUrl, parsed, options, describeMissingTarget) {
+    const visibility = await ProbeRepoVisibility(repoUrl, parsed, options);
+    switch (visibility.State) {
+        case 'Readable':
+            return describeMissingTarget();
+        case 'NotReadable':
+            return UnreadableRepoMessage(repoUrl, parsed, options);
+        case 'Undetermined':
+            return `Could not confirm ${parsed.Owner}/${parsed.Repo} is readable: ${visibility.Reason}. `
+                + `If it is private, a GitHub credential may be required — ${CONFIGURE_CREDENTIAL_REMEDY}. `
+                + `If it is readable, then: ${describeMissingTarget()}`;
+    }
+}
 async function FetchFileContent(octokit, owner, repo, path, ref) {
     const { data } = await octokit.repos.getContent({ owner, repo, path, ref });
     if (Array.isArray(data) || data.type !== 'file') {
@@ -103,9 +197,22 @@ async function ListDirectory(octokit, owner, repo, path, ref) {
     return data.map(item => ({ name: item.name, path: item.path, type: item.type, sha: item.sha }));
 }
 function ScopedTagPrefix(subpath) {
-    const s = subpath?.replace(/^\/+|\/+$/g, '');
+    const s = SubpathOrUndefined(subpath);
     return s ? s.replace(/\//g, '-') : undefined;
 }
+function ScopedTagCandidates(subpath, appName) {
+    const out = [];
+    const folder = ScopedTagPrefix(subpath);
+    if (folder)
+        out.push(folder);
+    const name = appName?.trim();
+    if (name && name !== folder)
+        out.push(name);
+    return out;
+}
+function EscapeForRegExp(v) {
+    return v.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
 function ResolveRef(version, subpath) {
     if (!version)
         return 'HEAD';
@@ -114,15 +221,18 @@ function ResolveRef(version, subpath) {
     return prefix ? `${prefix}@${v}` : `v${v}`;
 }
 function ComposeRepoPath(effectiveSubpath, relativePath) {
-    return [effectiveSubpath, relativePath.replace(/^\/|\/$/g, '')].filter(Boolean).join('/');
+    return [effectiveSubpath, TrimSlashes(relativePath)].filter(Boolean).join('/');
 }
-export async function FetchManifestFromGitHub(repoUrl, version, options, subpath) {
+export async function FetchManifestFromGitHub(repoUrl, version, options, subpath, appName) {
     const parsed = ParseGitHubUrl(repoUrl);
     if (!parsed) {
         return { Success: false, ErrorMessage: `Invalid GitHub URL: ${repoUrl}` };
     }
-    const effectiveSubpath = (subpath ?? parsed.Subpath)?.replace(/^\/+|\/+$/g, '');
-    const ref = ResolveRef(version, effectiveSubpath);
+    const effectiveSubpath = SubpathOrUndefined(subpath ?? parsed.Subpath);
+    const ref = version
+        ? (await FindVersionTagName(repoUrl, options, version, effectiveSubpath, appName))
+            ?? ResolveRef(version, effectiveSubpath)
+        : ResolveRef(version, effectiveSubpath);
     const manifestPath = ComposeRepoPath(effectiveSubpath, 'mj-app.json');
     try {
         const content = await FetchFileContent(CreateOctokit(repoUrl, options), parsed.Owner, parsed.Repo, manifestPath, ref);
@@ -130,7 +240,10 @@ export async function FetchManifestFromGitHub(repoUrl, version, options, subpath
     }
     catch (error) {
         if (OctokitStatus(error) === 404) {
-            return { Success: false, ErrorMessage: `${manifestPath} not found in ${parsed.Owner}/${parsed.Repo} at ref ${ref}` };
+            return {
+                Success: false,
+                ErrorMessage: await DescribeNotFound(repoUrl, parsed, options, () => `${manifestPath} not found in ${parsed.Owner}/${parsed.Repo} at ref ${ref}`),
+            };
         }
         const message = error instanceof Error ? error.message : String(error);
         return { Success: false, ErrorMessage: `Failed to fetch manifest: ${message}` };
@@ -168,7 +281,7 @@ async function listSqlFilesRecursive(octokit, owner, repo, root, ref, currentDir
     const out = [];
     for (const item of items) {
         if (item.type === 'file' && item.name.endsWith('.sql')) {
-            out.push({ path: item.path, relativePath: item.path.slice(root.length).replace(/^\/+/, '') });
+            out.push({ path: item.path, relativePath: TrimLeadingSlashes(item.path.slice(root.length)) });
         }
         else if (item.type === 'dir') {
             out.push(...await listSqlFilesRecursive(octokit, owner, repo, root, ref, item.path, depth + 1));
@@ -176,18 +289,207 @@ async function listSqlFilesRecursive(octokit, owner, repo, root, ref, currentDir
     }
     return out;
 }
-export async function DownloadMigrations(repoUrl, version, migrationsPath, localDir, options, subpath) {
+function IsZeroBlock(block) {
+    for (let i = 0; i < block.length; i++) {
+        if (block[i] !== 0)
+            return false;
+    }
+    return true;
+}
+function ReadNullTerminatedString(buf) {
+    const nulIdx = buf.indexOf(0);
+    return buf.subarray(0, nulIdx >= 0 ? nulIdx : buf.length).toString('utf-8');
+}
+function ReadUstarPath(header) {
+    const name = ReadNullTerminatedString(header.subarray(0, 100));
+    const prefix = ReadNullTerminatedString(header.subarray(345, 500));
+    return prefix ? `${prefix}/${name}` : name;
+}
+function ParseTarSize(sizeField) {
+    if ((sizeField[0] & 0x80) !== 0) {
+        let value = 0;
+        for (let i = 1; i < sizeField.length; i++) {
+            value = value * 256 + sizeField[i];
+        }
+        if (!Number.isSafeInteger(value) || value < 0) {
+            throw new Error(`Corrupt tar archive: invalid binary entry size ${value}`);
+        }
+        return value;
+    }
+    const octal = ReadNullTerminatedString(sizeField).trim();
+    if (!octal)
+        return 0;
+    if (!/^[0-7]+$/.test(octal)) {
+        throw new Error(`Corrupt tar archive: invalid octal size '${octal}'`);
+    }
+    const parsed = parseInt(octal, 8);
+    if (!Number.isSafeInteger(parsed) || parsed < 0) {
+        throw new Error(`Corrupt tar archive: invalid entry size ${parsed}`);
+    }
+    return parsed;
+}
+function ParsePaxHeader(paxBuf) {
+    const result = {};
+    let pos = 0;
+    while (pos < paxBuf.length) {
+        const spaceIdx = paxBuf.indexOf(0x20, pos);
+        if (spaceIdx < 0)
+            break;
+        const recordLen = parseInt(paxBuf.subarray(pos, spaceIdx).toString('ascii'), 10);
+        if (!Number.isFinite(recordLen) || recordLen <= 0 || pos + recordLen > paxBuf.length)
+            break;
+        const body = paxBuf.subarray(spaceIdx + 1, pos + recordLen - 1).toString('utf-8');
+        const eqIdx = body.indexOf('=');
+        if (eqIdx > 0) {
+            const key = body.slice(0, eqIdx);
+            const val = body.slice(eqIdx + 1);
+            if (key === 'path') {
+                result.Path = val;
+            }
+            else if (key === 'size') {
+                const trimmedVal = val.trim();
+                if (!/^\d+$/.test(trimmedVal)) {
+                    throw new Error(`Corrupt tar archive: invalid PAX size '${val}'`);
+                }
+                const parsedSize = parseInt(trimmedVal, 10);
+                if (!Number.isSafeInteger(parsedSize) || parsedSize < 0) {
+                    throw new Error(`Corrupt tar archive: invalid PAX size ${parsedSize}`);
+                }
+                result.Size = parsedSize;
+            }
+        }
+        pos += recordLen;
+    }
+    return result;
+}
+function ToTarballBuffer(data) {
+    if (Buffer.isBuffer(data))
+        return data;
+    if (data instanceof ArrayBuffer)
+        return Buffer.from(data);
+    if (ArrayBuffer.isView(data))
+        return Buffer.from(data.buffer, data.byteOffset, data.byteLength);
+    if (typeof data === 'string')
+        return Buffer.from(data, 'binary');
+    throw new Error('Unexpected tarball response data type from GitHub API');
+}
+export function ExtractSqlFilesFromTarGz(tarGzBuffer, cleanPath, localDir) {
+    const tarBuffer = gunzipSync(tarGzBuffer, { maxOutputLength: 512 * 1024 * 1024 });
+    const normalizedRoot = TrimSlashes(cleanPath);
+    const rootPrefix = normalizedRoot ? `${normalizedRoot}/` : '';
+    const extractedFiles = [];
+    let offset = 0;
+    let paxPathOverride;
+    let paxSizeOverride;
+    let gnuLongPathOverride;
+    while (offset + 512 <= tarBuffer.length) {
+        const header = tarBuffer.subarray(offset, offset + 512);
+        offset += 512;
+        if (IsZeroBlock(header)) {
+            break;
+        }
+        const typeFlagByte = header[156];
+        const typeFlag = typeFlagByte === 0 ? '0' : String.fromCharCode(typeFlagByte);
+        const entrySize = paxSizeOverride ?? ParseTarSize(header.subarray(124, 136));
+        if (!Number.isSafeInteger(entrySize) || entrySize < 0) {
+            throw new Error(`Corrupt tar archive: invalid entry size ${entrySize}`);
+        }
+        const dataOffset = offset;
+        const paddedSize = Math.ceil(entrySize / 512) * 512;
+        offset += paddedSize;
+        if (dataOffset + entrySize > tarBuffer.length) {
+            throw new Error('Corrupt tar archive: entry extends past end of buffer');
+        }
+        if (typeFlag === 'x') {
+            const parsedPax = ParsePaxHeader(tarBuffer.subarray(dataOffset, dataOffset + entrySize));
+            if (parsedPax.Path !== undefined)
+                paxPathOverride = parsedPax.Path;
+            if (parsedPax.Size !== undefined)
+                paxSizeOverride = parsedPax.Size;
+            continue;
+        }
+        if (typeFlag === 'L') {
+            gnuLongPathOverride = ReadNullTerminatedString(tarBuffer.subarray(dataOffset, dataOffset + entrySize));
+            continue;
+        }
+        if (typeFlag === 'g' || typeFlag === 'K') {
+            continue;
+        }
+        const rawEntryPath = paxPathOverride ?? gnuLongPathOverride ?? ReadUstarPath(header);
+        paxPathOverride = undefined;
+        paxSizeOverride = undefined;
+        gnuLongPathOverride = undefined;
+        if (typeFlag !== '0') {
+            continue;
+        }
+        const firstSlash = rawEntryPath.indexOf('/');
+        if (firstSlash < 0) {
+            continue;
+        }
+        const repoRelativePath = rawEntryPath.slice(firstSlash + 1);
+        if (!repoRelativePath.startsWith(rootPrefix) || !repoRelativePath.endsWith('.sql')) {
+            continue;
+        }
+        const relativePath = TrimLeadingSlashes(repoRelativePath.slice(rootPrefix.length));
+        if (!relativePath) {
+            continue;
+        }
+        if (relativePath.includes('\\')) {
+            throw new Error(`Refusing to extract migration path with backslash separator: '${relativePath}'`);
+        }
+        const segments = relativePath.split('/').filter(Boolean);
+        if (segments.some(seg => seg === '..' || seg === '.')) {
+            throw new Error(`Refusing to extract migration path with traversal segment: '${relativePath}'`);
+        }
+        const depth = segments.length - 1;
+        if (depth > MAX_MIGRATION_DIRECTORY_DEPTH) {
+            throw new Error(`Migration directory nesting exceeds ${MAX_MIGRATION_DIRECTORY_DEPTH} levels under '${normalizedRoot}' — `
+                + `refusing to walk further. No real migration layout is this deep.`);
+        }
+        const target = join(localDir, ...segments);
+        const targetDir = dirname(target);
+        if (!existsSync(targetDir)) {
+            mkdirSync(targetDir, { recursive: true });
+        }
+        writeFileSync(target, tarBuffer.subarray(dataOffset, dataOffset + entrySize));
+        extractedFiles.push(segments.join('/'));
+    }
+    return extractedFiles;
+}
+export async function DownloadMigrations(repoUrl, version, migrationsPath, localDir, options, subpath, appName) {
     const parsed = ParseGitHubUrl(repoUrl);
     if (!parsed) {
         return { Success: false, ErrorMessage: `Invalid GitHub URL: ${repoUrl}` };
     }
-    const effectiveSubpath = (subpath ?? parsed.Subpath)?.replace(/^\/+|\/+$/g, '');
-    const ref = ResolveRef(version, effectiveSubpath);
+    const effectiveSubpath = SubpathOrUndefined(subpath ?? parsed.Subpath);
+    const ref = version
+        ? (await FindVersionTagName(repoUrl, options, version, effectiveSubpath, appName))
+            ?? ResolveRef(version, effectiveSubpath)
+        : ResolveRef(version, effectiveSubpath);
     const cleanPath = ComposeRepoPath(effectiveSubpath, migrationsPath);
     const octokit = CreateOctokit(repoUrl, options);
     try {
-        const sqlFiles = await listSqlFilesRecursive(octokit, parsed.Owner, parsed.Repo, cleanPath, ref);
-        if (sqlFiles.length === 0) {
+        let downloadedFiles;
+        const canDownloadTarball = typeof octokit.repos.downloadTarballArchive === 'function';
+        if (canDownloadTarball) {
+            const tarGzBuffer = await FetchRepoTarball(octokit, repoUrl, parsed, ref, options);
+            downloadedFiles = ExtractSqlFilesFromTarGz(tarGzBuffer, cleanPath, localDir);
+        }
+        else {
+            const sqlFiles = await listSqlFilesRecursive(octokit, parsed.Owner, parsed.Repo, cleanPath, ref);
+            downloadedFiles = [];
+            for (const file of sqlFiles) {
+                const content = await FetchFileContent(octokit, parsed.Owner, parsed.Repo, file.path, ref);
+                const target = join(localDir, file.relativePath);
+                const targetDir = dirname(target);
+                if (!existsSync(targetDir)) {
+                    mkdirSync(targetDir, { recursive: true });
+                }
+                writeFileSync(target, content, 'utf-8');
+                downloadedFiles.push(file.relativePath);
+            }
+        }
+        if (downloadedFiles.length === 0) {
             return {
                 Success: false,
                 ErrorMessage: `No .sql files found under '${cleanPath}' (ref: ${ref ?? 'default branch'}). `
@@ -195,17 +497,6 @@ export async function DownloadMigrations(repoUrl, version, migrationsPath, local
                     + `check 'migrations.directory' in mj-app.json and that the tag's tree contains it.`,
             };
         }
-        const downloadedFiles = [];
-        for (const file of sqlFiles) {
-            const content = await FetchFileContent(octokit, parsed.Owner, parsed.Repo, file.path, ref);
-            const target = join(localDir, file.relativePath);
-            const targetDir = dirname(target);
-            if (!existsSync(targetDir)) {
-                mkdirSync(targetDir, { recursive: true });
-            }
-            writeFileSync(target, content, 'utf-8');
-            downloadedFiles.push(file.relativePath);
-        }
         return { Success: true, LocalPath: localDir, Files: downloadedFiles };
     }
     catch (error) {
@@ -213,8 +504,16 @@ export async function DownloadMigrations(repoUrl, version, migrationsPath, local
         return { Success: false, ErrorMessage: `Failed to download migrations: ${message}` };
     }
 }
-export async function GetLatestVersion(repoUrl, options, subpath) {
-    if (!ScopedTagPrefix(subpath ?? ParseGitHubUrl(repoUrl)?.Subpath)) {
+export async function DescribeUnresolvedVersion(repoUrl, options, subpath) {
+    const parsed = ParseGitHubUrl(repoUrl);
+    if (!parsed) {
+        return `Invalid GitHub URL: ${repoUrl}`;
+    }
+    const where = subpath ? `${parsed.Owner}/${parsed.Repo} (${subpath})` : `${parsed.Owner}/${parsed.Repo}`;
+    return DescribeNotFound(repoUrl, parsed, options, () => `Could not determine target version: no version tags or releases found in ${where}`);
+}
+export async function GetLatestVersion(repoUrl, options, subpath, appName) {
+    if (ScopedTagCandidates(subpath ?? ParseGitHubUrl(repoUrl)?.Subpath, appName).length === 0) {
         const releases = await ListGitHubReleases(repoUrl, options);
         const versioned = releases
             .filter(r => !r.PreRelease && !r.Draft)
@@ -226,26 +525,52 @@ export async function GetLatestVersion(repoUrl, options, subpath) {
             return candidates.sort(semver.rcompare)[0];
         }
     }
-    const tags = await ListGitHubTags(repoUrl, options, subpath);
+    const tags = await ListGitHubTags(repoUrl, options, subpath, appName);
     if (tags.length > 0) {
         const stableTag = tags.find(t => !IsPrereleaseVersion(t));
         return (stableTag ?? tags[0]).replace(/^v/, '');
     }
     return null;
 }
-export async function ListGitHubTags(repoUrl, options, subpath) {
+export async function FindVersionTagName(repoUrl, options, version, subpath, appName) {
+    const parsed = ParseGitHubUrl(repoUrl);
+    if (!parsed)
+        return null;
+    const candidates = ScopedTagCandidates(subpath ?? parsed.Subpath, appName);
+    if (candidates.length === 0)
+        return null;
+    const want = version.replace(/^v/, '');
+    const pattern = new RegExp(`^(?:@[^/]+/)?(?:${candidates.map(EscapeForRegExp).join('|')})@(.+)$`);
+    try {
+        for (const name of await FetchRepoTagNames(repoUrl, parsed, options)) {
+            const m = name.match(pattern);
+            if (m && m[1].replace(/^v/, '') === want)
+                return name;
+        }
+        return null;
+    }
+    catch (error) {
+        ThrowIfRateLimitedOrForbidden(error, 'resolving version tag');
+        return null;
+    }
+}
+export async function ListGitHubTags(repoUrl, options, subpath, appName) {
     const parsed = ParseGitHubUrl(repoUrl);
     if (!parsed) {
         return [];
     }
-    const prefix = ScopedTagPrefix(subpath ?? parsed.Subpath);
+    const candidates = ScopedTagCandidates(subpath ?? parsed.Subpath, appName);
+    const prefix = candidates.length > 0 ? candidates[0] : undefined;
+    const isMultiAppRepo = ScopedTagPrefix(subpath ?? parsed.Subpath) !== undefined;
     const SEMVER_PATTERN = '\\d+\\.\\d+\\.\\d+(-[a-zA-Z0-9]+(\\.[a-zA-Z0-9]+)*)?';
-    const pattern = prefix
-        ? new RegExp(`^${prefix.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}@(${SEMVER_PATTERN})$`)
-        : new RegExp(`^(v?${SEMVER_PATTERN})$`);
+    const scopedPattern = prefix
+        ? new RegExp(`^(?:@[^/]+/)?(?:${candidates.map(EscapeForRegExp).join('|')})@(${SEMVER_PATTERN})$`)
+        : null;
+    const repoWidePattern = isMultiAppRepo ? null : new RegExp(`^(v?${SEMVER_PATTERN})$`);
+    const matchVersion = (name) => (scopedPattern ? name.match(scopedPattern)?.[1] : undefined) ?? (repoWidePattern ? name.match(repoWidePattern)?.[1] : undefined);
     try {
         return (await FetchRepoTagNames(repoUrl, parsed, options))
-            .map(name => name.match(pattern)?.[1])
+            .map(name => matchVersion(name))
             .filter((v) => v != null)
             .map(tag => ({ Tag: tag, Core: SemverCore(tag) }))
             .filter((t) => t.Core !== null)
@@ -260,10 +585,42 @@ export async function ListGitHubTags(repoUrl, options, subpath) {
 const TAG_CACHE_TTL_MS = 60_000;
 const tagListCache = new Map();
 const releaseListCache = new Map();
+const tarballCache = new Map();
+const TARBALL_CACHE_MAX_ENTRIES = 2;
 const FETCH_CACHE_MAX_ENTRIES = 64;
 export function ClearGitHubTagCache() {
     tagListCache.clear();
     releaseListCache.clear();
+    tarballCache.clear();
+}
+async function FetchRepoTarball(octokit, repoUrl, parsed, ref, options) {
+    const cacheKey = `${FetchCacheKey(repoUrl, parsed, options)}\u0000${ref}`;
+    const now = Date.now();
+    const cached = tarballCache.get(cacheKey);
+    if (cached && cached.ExpiresAt > now) {
+        return await cached.Value;
+    }
+    for (const [key, entry] of tarballCache) {
+        if (entry.ExpiresAt <= now)
+            tarballCache.delete(key);
+    }
+    while (tarballCache.size >= TARBALL_CACHE_MAX_ENTRIES) {
+        const oldest = tarballCache.keys().next();
+        if (oldest.done)
+            break;
+        tarballCache.delete(oldest.value);
+    }
+    const inFlight = (async () => {
+        const response = await octokit.repos.downloadTarballArchive({
+            owner: parsed.Owner,
+            repo: parsed.Repo,
+            ref,
+        });
+        return ToTarballBuffer(response.data);
+    })();
+    tarballCache.set(cacheKey, { ExpiresAt: now + TAG_CACHE_TTL_MS, Value: inFlight });
+    inFlight.catch(() => { tarballCache.delete(cacheKey); });
+    return await inFlight;
 }
 async function MemoizedFetch(cache, cacheKey, fetcher) {
     const now = Date.now();
@@ -296,19 +653,23 @@ async function FetchRepoTagNames(repoUrl, parsed, options) {
         return data.map(t => t.name);
     });
 }
-export async function ValidateGitHubTag(repoUrl, version, options, subpath) {
+export async function ValidateGitHubTag(repoUrl, version, options, subpath, appName) {
     const parsed = ParseGitHubUrl(repoUrl);
     if (!parsed) {
         return { Exists: false, ErrorMessage: `Invalid GitHub URL: ${repoUrl}` };
     }
-    const tag = ResolveRef(version, subpath ?? parsed.Subpath);
+    const tag = (await FindVersionTagName(repoUrl, options, version, subpath ?? parsed.Subpath, appName))
+        ?? ResolveRef(version, subpath ?? parsed.Subpath);
     try {
         await CreateOctokit(repoUrl, options).git.getRef({ owner: parsed.Owner, repo: parsed.Repo, ref: `tags/${tag}` });
         return { Exists: true };
     }
     catch (error) {
         if (OctokitStatus(error) === 404) {
-            return { Exists: false, ErrorMessage: `Tag '${tag}' not found in ${parsed.Owner}/${parsed.Repo}. Available versions can be checked at ${repoUrl}/tags` };
+            return {
+                Exists: false,
+                ErrorMessage: await DescribeNotFound(repoUrl, parsed, options, () => `Tag '${tag}' not found in ${parsed.Owner}/${parsed.Repo}. Available versions can be checked at https://github.com/${parsed.Owner}/${parsed.Repo}/tags`),
+            };
         }
         const message = error instanceof Error ? error.message : String(error);
         return { Exists: false, ErrorMessage: `Failed to validate tag '${tag}': ${message}` };