@mindfoldhq/trellis 0.5.0-beta.8 → 0.5.0-rc.0

package/dist/utils/template-fetcher.d.ts

@@ -21,6 +21,19 @@ export interface SpecTemplate {
     tags?: string[];
 }
 export type TemplateStrategy = "skip" | "overwrite" | "append";
+export type RegistryBackend = "http" | "git";
+export type RegistrySourceKind = "prefixed" | "https" | "ssh";
+export type RegistryErrorKind = "auth" | "git-unavailable" | "invalid-json" | "network" | "not-found" | "path-not-found" | "ref-not-found" | "unknown";
+export declare class RegistryBackendError extends Error {
+    readonly kind: RegistryErrorKind;
+    constructor(kind: RegistryErrorKind, message: string);
+}
+export interface RegistryProbeResult {
+    templates: SpecTemplate[];
+    isNotFound: boolean;
+    backend: RegistryBackend;
+    error?: RegistryBackendError;
+}
 export interface RegistrySource {
     /** Original provider prefix (e.g., "gh", "gitlab", "bitbucket") */
     provider: string;
@@ -36,6 +49,12 @@ export interface RegistrySource {
     gigetSource: string;
     /** Custom host for self-hosted instances (e.g., "git.company.com"). Undefined for public providers. */
     host?: string;
+    /** Git remote URL used by git-backed registry access. */
+    gitUrl: string;
+    /** Whether registry access should prefer Git over anonymous raw HTTP. */
+    preferGit: boolean;
+    /** Input family used to derive credential behavior and clone URL shape. */
+    sourceKind: RegistrySourceKind;
 }
 export declare const SUPPORTED_PROVIDERS: string[];
 /**
@@ -81,10 +100,7 @@ export declare function fetchTemplateIndex(indexUrl?: string): Promise<SpecTempl
  * - Other HTTP error / network timeout → { templates: [], isNotFound: false }
  * - 200 + valid JSON → { templates: [...], isNotFound: false }
  */
-export declare function probeRegistryIndex(indexUrl: string): Promise<{
-    templates: SpecTemplate[];
-    isNotFound: boolean;
-}>;
+export declare function probeRegistryIndex(indexUrl: string, registry?: RegistrySource): Promise<RegistryProbeResult>;
 /**
  * Find a template by ID from the index
  */
@@ -117,7 +133,7 @@ export declare function downloadWithStrategy(templatePath: string, destDir: stri
  *                   repo as the giget source instead of the default TEMPLATE_REPO.
  * @returns Object with success status and message
  */
-export declare function downloadTemplateById(cwd: string, templateId: string, strategy: TemplateStrategy, template?: SpecTemplate, registry?: RegistrySource, destDirOverride?: string): Promise<{
+export declare function downloadTemplateById(cwd: string, templateId: string, strategy: TemplateStrategy, template?: SpecTemplate, registry?: RegistrySource, destDirOverride?: string, registryBackend?: RegistryBackend): Promise<{
     success: boolean;
     message: string;
     skipped?: boolean;
@@ -126,7 +142,7 @@ export declare function downloadTemplateById(cwd: string, templateId: string, st
  * Download a registry source directly to the spec directory (no index.json).
  * Used when the registry source points to a spec directory, not a marketplace.
  */
-export declare function downloadRegistryDirect(cwd: string, registry: RegistrySource, strategy: TemplateStrategy, destDirOverride?: string): Promise<{
+export declare function downloadRegistryDirect(cwd: string, registry: RegistrySource, strategy: TemplateStrategy, destDirOverride?: string, registryBackend?: RegistryBackend): Promise<{
     success: boolean;
     message: string;
     skipped?: boolean;

package/dist/utils/template-fetcher.d.ts.map

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

package/dist/utils/template-fetcher.js

@@ -27,6 +27,14 @@ export const TIMEOUTS = {
     /** Timeout for downloading a template via giget (ms) */
     DOWNLOAD_MS: 30_000,
 };
+export class RegistryBackendError extends Error {
+    kind;
+    constructor(kind, message) {
+        super(message);
+        this.name = "RegistryBackendError";
+        this.kind = kind;
+    }
+}
 // =============================================================================
 // Registry Source Parsing
 // =============================================================================
@@ -74,6 +82,29 @@ const PUBLIC_DOMAIN_TO_PREFIX = {
     "gitlab.com": "gitlab",
     "bitbucket.org": "bitbucket",
 };
+function buildRegistryGitUrl(input) {
+    if (input.sourceKind === "ssh" && input.sshHost) {
+        if (input.sshStyle === "ssh-url") {
+            const port = input.sshPort ? `:${input.sshPort}` : "";
+            return `ssh://git@${input.sshHost}${port}/${input.repo}.git`;
+        }
+        return `git@${input.sshHost}:${input.repo}.git`;
+    }
+    if (input.host) {
+        return `https://${input.host}/${input.repo}.git`;
+    }
+    switch (input.provider) {
+        case "gh":
+        case "github":
+            return `https://github.com/${input.repo}.git`;
+        case "gitlab":
+            return `https://gitlab.com/${input.repo}.git`;
+        case "bitbucket":
+            return `https://bitbucket.org/${input.repo}.git`;
+        default:
+            return input.repo;
+    }
+}
 /**
  * Parse a giget-style registry source into its components.
  *
@@ -98,12 +129,20 @@ export function parseRegistrySource(source) {
     // --- Self-hosted URL detection (SSH + unknown HTTPS) ---
     let host;
     let normalizedInput;
+    let sourceKind = "prefixed";
+    let sshHost;
+    let sshPort;
+    let sshStyle;
     // SSH URL: git@host:org/repo[.git] or ssh://git@host[:port]/org/repo[.git]
-    const sshMatch = source.match(/^git@([^:]+):(.+?)(?:\.git)?\/?$/) ??
-        source.match(/^ssh:\/\/git@([^/:]+)(?::\d+)?\/(.+?)(?:\.git)?\/?$/);
-    if (sshMatch) {
-        const sshDomain = sshMatch[1];
-        const sshPath = sshMatch[2];
+    const scpSshMatch = source.match(/^git@([^:]+):(.+?)(?:\.git)?\/?$/);
+    const protocolSshMatch = source.match(/^ssh:\/\/git@([^/:]+)(?::(\d+))?\/(.+?)(?:\.git)?\/?$/);
+    if (scpSshMatch || protocolSshMatch) {
+        sourceKind = "ssh";
+        sshStyle = scpSshMatch ? "scp" : "ssh-url";
+        const sshDomain = scpSshMatch?.[1] ?? protocolSshMatch?.[1] ?? "";
+        const sshPath = scpSshMatch?.[2] ?? protocolSshMatch?.[3] ?? "";
+        sshPort = protocolSshMatch?.[2];
+        sshHost = sshDomain;
         const publicPrefix = PUBLIC_DOMAIN_TO_PREFIX[sshDomain];
         if (publicPrefix) {
             // Public provider SSH (e.g., git@github.com:org/repo) — use native prefix, no host
@@ -116,9 +155,10 @@ export function parseRegistrySource(source) {
         }
     }
     // HTTPS URL to unknown domain (not github.com/gitlab.com/bitbucket.org)
-    if (!host) {
+    if (!normalizedInput) {
         const httpsMatch = source.match(/^https?:\/\/([^/]+)\/(.+?)(?:\.git)?\/?$/);
         if (httpsMatch) {
+            sourceKind = "https";
             const domain = httpsMatch[1];
             if (!KNOWN_PUBLIC_DOMAINS.includes(domain)) {
                 host = domain;
@@ -176,7 +216,28 @@ export function parseRegistrySource(source) {
     }
     // Build giget source (use normalized format)
     const gigetSource = normalized;
-    return { provider, repo, subdir, ref, rawBaseUrl, gigetSource, host };
+    const gitUrl = buildRegistryGitUrl({
+        provider,
+        host,
+        repo,
+        sourceKind,
+        sshHost,
+        sshPort,
+        sshStyle,
+    });
+    const preferGit = sourceKind === "ssh" || host !== undefined;
+    return {
+        provider,
+        repo,
+        subdir,
+        ref,
+        rawBaseUrl,
+        gigetSource,
+        host,
+        gitUrl,
+        preferGit,
+        sourceKind,
+    };
 }
 // =============================================================================
 // Helpers
@@ -240,6 +301,81 @@ export async function fetchTemplateIndex(indexUrl) {
         return [];
     }
 }
+function isRecord(value) {
+    return typeof value === "object" && value !== null;
+}
+function parseTemplateIndex(raw, sourceLabel) {
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (error) {
+        const detail = error instanceof Error ? error.message : String(error);
+        throw new RegistryBackendError("invalid-json", `${sourceLabel} is not valid JSON: ${detail}`);
+    }
+    if (!isRecord(parsed) || !Array.isArray(parsed.templates)) {
+        throw new RegistryBackendError("invalid-json", `${sourceLabel} must contain a templates array.`);
+    }
+    const templates = [];
+    for (const item of parsed.templates) {
+        if (!isRecord(item)) {
+            throw new RegistryBackendError("invalid-json", `${sourceLabel} contains an invalid template entry.`);
+        }
+        const { id, type, name, description, path: templatePath, tags } = item;
+        if (typeof id !== "string" ||
+            typeof type !== "string" ||
+            typeof name !== "string" ||
+            typeof templatePath !== "string") {
+            throw new RegistryBackendError("invalid-json", `${sourceLabel} template entries must include string id, type, name, and path fields.`);
+        }
+        templates.push({
+            id,
+            type,
+            name,
+            path: templatePath,
+            ...(typeof description === "string" ? { description } : {}),
+            ...(Array.isArray(tags) && tags.every((tag) => typeof tag === "string")
+                ? { tags }
+                : {}),
+        });
+    }
+    const version = typeof parsed.version === "number" ? parsed.version : 1;
+    return { version, templates };
+}
+function emptyProbeResult(backend, isNotFound, error) {
+    return { templates: [], isNotFound, backend, ...(error ? { error } : {}) };
+}
+function shouldFallbackToGit(registry, result) {
+    if (registry?.provider !== "gitlab")
+        return false;
+    if (result.backend !== "http" || result.isNotFound)
+        return false;
+    return result.error?.kind === "auth" || result.error?.kind === "invalid-json";
+}
+async function probeRegistryIndexHttp(indexUrl) {
+    try {
+        const res = await fetch(indexUrl, {
+            signal: AbortSignal.timeout(TIMEOUTS.INDEX_FETCH_MS),
+        });
+        if (res.status === 404) {
+            return emptyProbeResult("http", true);
+        }
+        if (res.status === 401 || res.status === 403) {
+            return emptyProbeResult("http", false, new RegistryBackendError("auth", `Registry index requires authentication (HTTP ${res.status}). Use a registry source accessible by your local Git credentials.`));
+        }
+        if (!res.ok) {
+            return emptyProbeResult("http", false, new RegistryBackendError("network", `Could not reach registry index (HTTP ${res.status}). Check your network connection and try again.`));
+        }
+        const index = parseTemplateIndex(await res.text(), "Registry index.json");
+        return { templates: index.templates, isNotFound: false, backend: "http" };
+    }
+    catch (error) {
+        if (error instanceof RegistryBackendError) {
+            return emptyProbeResult("http", false, error);
+        }
+        return emptyProbeResult("http", false, new RegistryBackendError("network", `Could not reach registry index: ${error instanceof Error ? error.message : String(error)}`));
+    }
+}
 /**
  * Probe a registry's index.json, distinguishing "not found" from transient errors.
  * Used by the registry flow to decide marketplace vs direct-download mode.
@@ -248,23 +384,177 @@ export async function fetchTemplateIndex(indexUrl) {
  * - Other HTTP error / network timeout → { templates: [], isNotFound: false }
  * - 200 + valid JSON → { templates: [...], isNotFound: false }
  */
-export async function probeRegistryIndex(indexUrl) {
-    try {
-        const res = await fetch(indexUrl, {
-            signal: AbortSignal.timeout(TIMEOUTS.INDEX_FETCH_MS),
+export async function probeRegistryIndex(indexUrl, registry) {
+    if (registry?.preferGit) {
+        return probeRegistryIndexGit(registry);
+    }
+    const httpResult = await probeRegistryIndexHttp(indexUrl);
+    if (registry && shouldFallbackToGit(registry, httpResult)) {
+        return probeRegistryIndexGit(registry);
+    }
+    return httpResult;
+}
+async function runGit(args) {
+    const { execFile } = await import("node:child_process");
+    return new Promise((resolve, reject) => {
+        execFile("git", args, {
+            encoding: "utf-8",
+            maxBuffer: 10 * 1024 * 1024,
+            timeout: TIMEOUTS.DOWNLOAD_MS,
+        }, (error, stdout, stderr) => {
+            if (error) {
+                const commandError = error;
+                commandError.stdout = stdout;
+                commandError.stderr = stderr;
+                reject(commandError);
+                return;
+            }
+            resolve({ stdout, stderr });
         });
-        if (res.status === 404) {
-            return { templates: [], isNotFound: true };
+    });
+}
+function getCommandErrorText(error) {
+    if (!(error instanceof Error))
+        return String(error);
+    const commandError = error;
+    return [commandError.message, commandError.stderr, commandError.stdout]
+        .filter((part) => typeof part === "string" && part.length > 0)
+        .join("\n");
+}
+function classifyGitError(error, stage, registry) {
+    const text = getCommandErrorText(error);
+    const lower = text.toLowerCase();
+    if (lower.includes("enoent") ||
+        lower.includes("not found: git") ||
+        lower.includes("spawn git")) {
+        return new RegistryBackendError("git-unavailable", 'Git is required to access this registry, but the "git" command was not found.');
+    }
+    if (lower.includes("authentication failed") ||
+        lower.includes("permission denied") ||
+        lower.includes("access denied") ||
+        lower.includes("could not read from remote repository") ||
+        lower.includes("terminal prompts disabled")) {
+        return new RegistryBackendError("auth", `Authentication failed or registry is not accessible via Git. Check your local Git credentials for ${registry.gitUrl}.`);
+    }
+    if (stage !== "clone" &&
+        (lower.includes("couldn't find remote ref") ||
+            lower.includes("could not find remote ref") ||
+            lower.includes("invalid reference") ||
+            lower.includes("reference is not a tree") ||
+            lower.includes("pathspec"))) {
+        return new RegistryBackendError("ref-not-found", `Registry ref "${registry.ref}" was not found in ${registry.gitUrl}.`);
+    }
+    if (lower.includes("could not resolve host") ||
+        lower.includes("failed to connect") ||
+        lower.includes("network is unreachable") ||
+        lower.includes("operation timed out") ||
+        lower.includes("timed out") ||
+        lower.includes("connection refused")) {
+        return new RegistryBackendError("network", `Could not reach registry ${registry.gitUrl}. Check your network connection and Git remote access.`);
+    }
+    if (stage === "clone" &&
+        (lower.includes("repository not found") ||
+            lower.includes("does not appear to be a git repository") ||
+            lower.includes("could not read from remote repository"))) {
+        return new RegistryBackendError("not-found", `Registry repository was not found or is not accessible: ${registry.gitUrl}.`);
+    }
+    return new RegistryBackendError("unknown", `Git registry operation failed: ${text}`);
+}
+async function cloneRegistryRef(registry) {
+    const dir = await fs.promises.mkdtemp(path.join(os.tmpdir(), "trellis-registry-"));
+    try {
+        try {
+            await runGit([
+                "clone",
+                "--filter=blob:none",
+                "--no-checkout",
+                registry.gitUrl,
+                dir,
+            ]);
         }
-        if (!res.ok) {
-            return { templates: [], isNotFound: false };
+        catch (error) {
+            throw classifyGitError(error, "clone", registry);
         }
-        const index = (await res.json());
-        return { templates: index.templates, isNotFound: false };
+        try {
+            await runGit([
+                "-C",
+                dir,
+                "fetch",
+                "--depth",
+                "1",
+                "origin",
+                registry.ref,
+            ]);
+            await runGit(["-C", dir, "checkout", "--detach", "FETCH_HEAD"]);
+        }
+        catch (error) {
+            throw classifyGitError(error, "fetch", registry);
+        }
+        return {
+            dir,
+            cleanup: async () => {
+                await fs.promises.rm(dir, { recursive: true, force: true });
+            },
+        };
+    }
+    catch (error) {
+        await fs.promises.rm(dir, { recursive: true, force: true });
+        throw error;
+    }
+}
+function resolveInsideRegistryRoot(root, relativePath, label) {
+    const resolvedRoot = path.resolve(root);
+    const resolved = path.resolve(resolvedRoot, relativePath.length > 0 ? relativePath : ".");
+    const relative = path.relative(resolvedRoot, resolved);
+    if (relative.startsWith("..") || path.isAbsolute(relative)) {
+        throw new RegistryBackendError("path-not-found", `${label} path "${relativePath}" must stay inside the registry repository.`);
+    }
+    return resolved;
+}
+async function isDirectory(dir) {
+    try {
+        return (await fs.promises.stat(dir)).isDirectory();
     }
     catch {
-        // Network error or timeout
-        return { templates: [], isNotFound: false };
+        return false;
+    }
+}
+async function isFile(filePath) {
+    try {
+        return (await fs.promises.stat(filePath)).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+async function getGitRegistryRoot(checkoutDir, registry) {
+    const registryRoot = resolveInsideRegistryRoot(checkoutDir, registry.subdir, "Registry");
+    if (!(await isDirectory(registryRoot))) {
+        throw new RegistryBackendError("path-not-found", `Registry path "${registry.subdir.length > 0 ? registry.subdir : "."}" was not found in ${registry.gitUrl}#${registry.ref}.`);
+    }
+    return registryRoot;
+}
+async function probeRegistryIndexGit(registry) {
+    try {
+        const checkout = await cloneRegistryRef(registry);
+        try {
+            const registryRoot = await getGitRegistryRoot(checkout.dir, registry);
+            const indexPath = path.join(registryRoot, "index.json");
+            if (!(await isFile(indexPath))) {
+                return emptyProbeResult("git", true);
+            }
+            const index = parseTemplateIndex(await fs.promises.readFile(indexPath, "utf-8"), "Registry index.json");
+            return { templates: index.templates, isNotFound: false, backend: "git" };
+        }
+        finally {
+            await checkout.cleanup();
+        }
+    }
+    catch (error) {
+        const registryError = error instanceof RegistryBackendError
+            ? error
+            : new RegistryBackendError("unknown", `Git registry probe failed: ${error instanceof Error ? error.message : String(error)}`);
+        return emptyProbeResult("git", false, registryError);
     }
 }
 /**
@@ -387,6 +677,64 @@ async function copyMissing(src, dest) {
         }
     }
 }
+/**
+ * Copy all files from src to dest, overwriting existing files.
+ */
+async function copyAll(src, dest) {
+    await fs.promises.mkdir(dest, { recursive: true });
+    const entries = await fs.promises.readdir(src, { withFileTypes: true });
+    for (const entry of entries) {
+        const srcPath = path.join(src, entry.name);
+        const destPath = path.join(dest, entry.name);
+        if (entry.isDirectory()) {
+            await copyAll(srcPath, destPath);
+        }
+        else {
+            await fs.promises.copyFile(srcPath, destPath);
+        }
+    }
+}
+async function copyDirectoryWithStrategy(srcDir, destDir, strategy) {
+    const exists = fs.existsSync(destDir);
+    if (strategy === "skip" && exists) {
+        return false;
+    }
+    if (strategy === "overwrite" && exists) {
+        await fs.promises.rm(destDir, { recursive: true, force: true });
+    }
+    if (strategy === "append" && exists) {
+        await copyMissing(srcDir, destDir);
+        return true;
+    }
+    await copyAll(srcDir, destDir);
+    return true;
+}
+async function downloadGitRegistryPath(registry, relativePath, destDir, strategy) {
+    const checkout = await cloneRegistryRef(registry);
+    try {
+        const sourceRoot = resolveInsideRegistryRoot(checkout.dir, relativePath, "Template");
+        if (!(await isDirectory(sourceRoot))) {
+            throw new RegistryBackendError("path-not-found", `Template path "${relativePath.length > 0 ? relativePath : "."}" was not found in ${registry.gitUrl}#${registry.ref}.`);
+        }
+        return await copyDirectoryWithStrategy(sourceRoot, destDir, strategy);
+    }
+    finally {
+        await checkout.cleanup();
+    }
+}
+async function downloadGitRegistryDirect(registry, destDir, strategy) {
+    const checkout = await cloneRegistryRef(registry);
+    try {
+        const sourceRoot = await getGitRegistryRoot(checkout.dir, registry);
+        return await copyDirectoryWithStrategy(sourceRoot, destDir, strategy);
+    }
+    finally {
+        await checkout.cleanup();
+    }
+}
+function resolveRegistryBackend(registry, backendOverride) {
+    return backendOverride ?? (registry.preferGit ? "git" : "http");
+}
 /**
  * Download a template by ID
  *
@@ -398,14 +746,22 @@ async function copyMissing(src, dest) {
  *                   repo as the giget source instead of the default TEMPLATE_REPO.
  * @returns Object with success status and message
  */
-export async function downloadTemplateById(cwd, templateId, strategy, template, registry, destDirOverride) {
+export async function downloadTemplateById(cwd, templateId, strategy, template, registry, destDirOverride, registryBackend) {
     // Use pre-fetched template or find from index
     let resolved = template;
+    let backend = registryBackend;
     if (!resolved) {
         const indexUrl = registry ? `${registry.rawBaseUrl}/index.json` : undefined;
         if (registry && indexUrl) {
             // Use probe to distinguish "template not in index" from "registry unreachable"
-            const probeResult = await probeRegistryIndex(indexUrl);
+            const probeResult = await probeRegistryIndex(indexUrl, registry);
+            backend = probeResult.backend;
+            if (probeResult.error) {
+                return {
+                    success: false,
+                    message: probeResult.error.message,
+                };
+            }
             if (probeResult.templates.length === 0 && !probeResult.isNotFound) {
                 return {
                     success: false,
@@ -450,10 +806,15 @@ export async function downloadTemplateById(cwd, templateId, strategy, template,
     // Download template
     try {
         if (registry) {
-            // Custom registry: build full giget source with ref at the end
-            // giget format: provider:user/repo/path#ref
-            const fullSource = `${registry.provider}:${registry.repo}/${resolved.path}#${registry.ref}`;
-            await withGigetHost(registry.host, () => downloadWithStrategy(fullSource, destDir, strategy, null));
+            if (resolveRegistryBackend(registry, backend) === "git") {
+                await downloadGitRegistryPath(registry, resolved.path, destDir, strategy);
+            }
+            else {
+                // Custom registry: build full giget source with ref at the end
+                // giget format: provider:user/repo/path#ref
+                const fullSource = `${registry.provider}:${registry.repo}/${resolved.path}#${registry.ref}`;
+                await withGigetHost(registry.host, () => downloadWithStrategy(fullSource, destDir, strategy, null));
+            }
         }
         else {
             await downloadWithStrategy(resolved.path, destDir, strategy);
@@ -465,6 +826,12 @@ export async function downloadTemplateById(cwd, templateId, strategy, template,
     }
     catch (error) {
         const errorMessage = error instanceof Error ? error.message : "Unknown error";
+        if (error instanceof RegistryBackendError) {
+            return {
+                success: false,
+                message: error.message,
+            };
+        }
         // Classify errors for user-friendly messages
         if (errorMessage.includes("timed out")) {
             return {
@@ -489,7 +856,7 @@ export async function downloadTemplateById(cwd, templateId, strategy, template,
  * Download a registry source directly to the spec directory (no index.json).
  * Used when the registry source points to a spec directory, not a marketplace.
  */
-export async function downloadRegistryDirect(cwd, registry, strategy, destDirOverride) {
+export async function downloadRegistryDirect(cwd, registry, strategy, destDirOverride, registryBackend) {
     const destDir = destDirOverride ?? getInstallPath(cwd, "spec");
     if (strategy === "skip" && fs.existsSync(destDir)) {
         return {
@@ -499,7 +866,12 @@ export async function downloadRegistryDirect(cwd, registry, strategy, destDirOve
         };
     }
     try {
-        await withGigetHost(registry.host, () => downloadWithStrategy(registry.gigetSource, destDir, strategy, null));
+        if (resolveRegistryBackend(registry, registryBackend) === "git") {
+            await downloadGitRegistryDirect(registry, destDir, strategy);
+        }
+        else {
+            await withGigetHost(registry.host, () => downloadWithStrategy(registry.gigetSource, destDir, strategy, null));
+        }
         return {
             success: true,
             message: `Downloaded spec from ${registry.gigetSource} to ${destDir}`,
@@ -507,6 +879,12 @@ export async function downloadRegistryDirect(cwd, registry, strategy, destDirOve
     }
     catch (error) {
         const errorMessage = error instanceof Error ? error.message : "Unknown error";
+        if (error instanceof RegistryBackendError) {
+            return {
+                success: false,
+                message: error.message,
+            };
+        }
         if (errorMessage.includes("timed out")) {
             return {
                 success: false,