import { createWriteStream } from "node:fs"; import { mkdir, rm } from "node:fs/promises"; import { existsSync, readdirSync } from "node:fs"; import { Readable } from "node:stream"; import { pipeline } from "node:stream/promises"; import { resolve, dirname } from "pathe"; import type { installDependencies } from "nypm"; import { cacheDirectory, download, debug, normalizeHeaders } from "./_utils.ts"; import { providers } from "./providers.ts"; import { registryProvider } from "./registry.ts"; import type { TemplateInfo, TemplateProvider } from "./types.ts"; type InstallOptions = Parameters[0]; export interface DownloadTemplateOptions { provider?: string; force?: boolean; forceClean?: boolean; offline?: boolean; preferOffline?: boolean; providers?: Record; dir?: string; registry?: false | string; cwd?: string; auth?: string; install?: boolean | InstallOptions; silent?: boolean; /** * Ignore files when extracting the template. * * Can be either: * - An array of glob patterns of files to ignore (skip extracting), matched * with [`path.matchesGlob`](https://nodejs.org/api/path.html#pathmatchesglobpath-pattern) * (Node.js >= v22.5.0 or v20.17.0). * - A callback receiving the relative path of each entry (after `subdir` is * applied) that returns `true` to skip the entry, or `false` to keep it. * * @example * // Ignore lockfiles via patterns * ignore: ["pnpm-lock.yaml", "*.lock"] * @example * // Ignore lockfiles via callback * ignore: (path) => /(?:^|\/)(?:pnpm-lock\.yaml|package-lock\.json|yarn\.lock)$/.test(path) */ ignore?: ((path: string) => boolean) | string[]; } const sourceProtoRe = /^([\w+-.]+):/; export type DownloadTemplateResult = Omit & { dir: string; source: string; }; function resolveIgnore( ignore: DownloadTemplateOptions["ignore"], ): ((path: string) => boolean) | undefined { if (!ignore) { return undefined; } if (typeof ignore === "function") { return ignore; } // Use `process.getBuiltinModule` for feature detection since a static // `import { matchesGlob }` fails to link on Node.js versions without it. const matchesGlob = globalThis.process.getBuiltinModule?.("node:path")?.matchesGlob; if (typeof matchesGlob !== "function") { throw new TypeError( "Ignore patterns require `path.matchesGlob` which is supported in Node.js v22.5.0, v20.17.0 or later.", ); } return (path) => ignore.some((pattern) => matchesGlob(path, pattern)); } export async function downloadTemplate( input: string, options: DownloadTemplateOptions = {}, ): Promise { const ignore = resolveIgnore(options.ignore); options.registry = process.env.GIGET_REGISTRY ?? options.registry; options.auth = process.env.GIGET_AUTH ?? options.auth; const registry = options.registry === false ? undefined : registryProvider(options.registry, { auth: options.auth }); let providerName: string = options.provider || (registry ? "registry" : "github"); let source: string = input; const sourceProviderMatch = input.match(sourceProtoRe); if (sourceProviderMatch) { providerName = sourceProviderMatch[1]!; source = input.slice(sourceProviderMatch[0].length); if (providerName === "http" || providerName === "https") { source = input; } } // Handle +git: prefix (e.g. gh+git:, github+git:, gitlab+git:) // Route to git provider with host prefix preserved for parseGitCloneURI if (providerName.endsWith("+git")) { const hostPrefix = providerName.slice(0, -4); // e.g. "gh", "github", "gitlab" source = `${hostPrefix}:${source}`; providerName = "git"; } const provider = options.providers?.[providerName] || providers[providerName] || registry; if (!provider) { throw new Error(`Unsupported provider: ${providerName}`); } const template = await Promise.resolve() .then(() => provider(source, { auth: options.auth })) .catch((error) => { throw new Error(`Failed to download template from ${providerName}: ${error.message}`); }); if (!template) { throw new Error(`Failed to resolve template from ${providerName}`); } // Sanitize name and defaultDir template.name = (template.name || "template").replace(/[^\da-z-]/gi, "-"); template.defaultDir = (template.defaultDir || template.name).replace(/[^\da-z-]/gi, "-"); // Download template source const temporaryDirectory = resolve(cacheDirectory(), providerName, template.name); const tarPath = resolve(temporaryDirectory, (template.version || template.name) + ".tar.gz"); if (options.preferOffline && existsSync(tarPath)) { options.offline = true; } if (!options.offline) { await mkdir(dirname(tarPath), { recursive: true }); const s = Date.now(); if (typeof template.tar === "function") { const tarFn = template.tar; await (async () => { const stream = await tarFn({ auth: options.auth }); const nodeStream = stream instanceof Readable ? stream : Readable.fromWeb(stream as import("node:stream/web").ReadableStream); const fileStream = createWriteStream(tarPath); await pipeline(nodeStream, fileStream); })().catch((error) => { if (!existsSync(tarPath)) { throw error; } debug("Download error. Using cached version:", error); options.offline = true; }); } else { await download(template.tar, tarPath, { headers: { Authorization: options.auth ? `Bearer ${options.auth}` : undefined, ...normalizeHeaders(template.headers), }, }).catch((error) => { if (!existsSync(tarPath)) { throw error; } // Accept network errors if we have a cached version debug("Download error. Using cached version:", error); options.offline = true; }); } debug(`Downloaded to ${tarPath} in ${Date.now() - s}ms`); } if (!existsSync(tarPath)) { throw new Error(`Tarball not found: ${tarPath} (offline: ${options.offline})`); } // Extract template const cwd = resolve(options.cwd || "."); const extractPath = resolve(cwd, options.dir || template.defaultDir); if (options.forceClean) { await rm(extractPath, { recursive: true, force: true }); } if (!options.force && existsSync(extractPath) && readdirSync(extractPath).length > 0) { throw new Error(`Destination ${extractPath} already exists.`); } await mkdir(extractPath, { recursive: true }); const s = Date.now(); const subdir = template.subdir?.replace(/^\//, "") || ""; const { extract } = await import("tar"); await extract({ file: tarPath, cwd: extractPath, onReadEntry(entry) { entry.path = entry.path.split("/").splice(1).join("/"); if (subdir) { if (entry.path.startsWith(subdir + "/")) { // Rewrite path entry.path = entry.path.slice(subdir.length); } else { // Skip entry.path = ""; } } if (ignore && entry.path && ignore(entry.path.replace(/^\//, ""))) { // Skip ignored entries entry.path = ""; } }, }); debug(`Extracted to ${extractPath} in ${Date.now() - s}ms`); if (options.install) { debug("Installing dependencies..."); const { installDependencies } = await import("nypm"); await installDependencies({ cwd: extractPath, silent: options.silent, ...(typeof options.install === "object" ? options.install : {}), }); } return { ...template, source, dir: extractPath, }; }