Skip to main content
This release is a pre-release — the latest non-prerelease version of @polyseam/cliffy-provider-gh-releases is 0.3.2. Jump to this version

Built and signed on GitHub Actions

Enables self-upgrading of a Cliffy CLI which is distributed through GitHub Releases

This package works with DenoIt is unknown whether this package works with Cloudflare Workers, Node.js, Bun, Browsers
It is unknown whether this package works with Cloudflare Workers
It is unknown whether this package works with Node.js
This package works with Deno
It is unknown whether this package works with Bun
It is unknown whether this package works with Browsers
JSR Score
100%
Published
a month ago (1.0.0-rc.11)
123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603
import { colors, ensureDirSync, homedir, inflateResponse, Octokit, Provider, semver, Spinner, UpgradeCommand, walkSync, } from "./deps.ts"; import type { OctokitEndpoints } from "./deps.ts"; import type { GithubProviderOptions, ProviderUpgradeOptions } from "./deps.ts"; const OLD_VERSION_TAG = ".GHR_OLD."; type AvailableOS = typeof Deno.build.os; type OSAssetMap = { [K in AvailableOS]?: string; }; type ReleaseResponse = OctokitEndpoints["GET /repos/{owner}/{repo}/releases/tags/{tag}"]["response"]; type ReleaseParameters = OctokitEndpoints["GET /repos/{owner}/{repo}/releases/tags/{tag}"][ "parameters" ]; type AssetParameters = OctokitEndpoints["GET /repos/{owner}/{repo}/releases/assets/{asset_id}"][ "parameters" ]; /** * ERROR_CODE_MAP * A map of error codes to human-readable error messages ***/ export const ERROR_CODE_MAP = { 1: "repository must be in the format 'owner/repo'", // Provider options configured incorrectly 2: "Found old version but failed to delete", // old version found but failed to delete 3: "No asset name found for the current OS", // asset name not found in osAssetMap 4: "No asset found for the current OS", // asset not found in release 5: "Network Error: failed to fetch GitHub Release Asset Data", // fetch() failed // 5xxx errors are for fetch() errors 5404: "Failed to fetch GitHub Release Asset Data - Not Found", 5500: "Failed to fetch GitHub Release Asset - Internal Server Error", // 6xxx errors are for octokit.request(data) errors 6404: "Failed to octokit.request GitHub Release Asset Data - Not Found", 6500: "Failed to octokit.request GitHub Release Asset Data - Internal Server Error", // 7xxx errors are for octokit.request(release list) errors 7404: "Failed to octokit.request Release List from GitHub - Not Found", 7500: "Failed to octokit.request Release List from GitHub - Internal Server Error", 8: "Failed to extract archive", // inflateResponse failed 9: "Failed to stash old version", // rename running bin failed 10: "Failed to install new version", // write new bin failed }; /** * GHRError * A simple Error object which includes a code and optional metadata * @param message - A human-readable error message * @param code - A numeric error code * @param metadata - An optional object containing additional error information */ export class GHRError extends Error { code: number; metadata: Record<string, unknown>; constructor(message: string, code: number, metadata = {}) { super(message); this.code = code; this.metadata = metadata; } } type OnCompleteMetadata = { to: string; from?: string; }; type OnCompleteFinalCallback = () => void; interface GithubReleasesProviderUpgradeOptions extends ProviderUpgradeOptions { } interface GithubReleasesProviderOptions extends GithubProviderOptions { destinationDir: string; displaySpinner?: boolean; prerelease?: boolean; untar?: boolean; cleanupOld?: boolean; osAssetMap: OSAssetMap; skipAuth?: boolean; repository: string; onComplete?: ( metadata: OnCompleteMetadata, cb: OnCompleteFinalCallback, ) => void | never; onError?: (error: GHRError) => void | never; } type GithubReleaseVersions = { versions: string[]; latest: string; }; function latestSemVerFirst(a: string, b: string): number { const aParsed = semver.tryParse(a); const bParsed = semver.tryParse(b); if (aParsed && bParsed) { // compare a and b in descending order return semver.compare(bParsed, aParsed); } else { return 0; // SemVer parsing failed in atleast one value, preserve order } } /** * GithubReleasesProvider * A Cliffy UpgradeProvider for GitHub Releases * @param options - An object containing the following properties: * - repository: A string in the format 'owner/repo' * - destinationDir: A string representing the directory where the release will be installed * - osAssetMap: An object mapping OS names to corresponding assets in GitHub Releases * - skipAuth: An optional boolean to skip authentication (not recommended) * - onError: An optional callback function to handle errors * - onComplete: An optional callback function to handle completion */ export class GithubReleasesProvider extends Provider { name: string = "GithubReleaseProvider"; displaySpinner: boolean = true; prerelease: boolean = false; destinationDir: string; octokit: Octokit; owner: string; repo: string; osAssetMap: OSAssetMap; cleanupOld: boolean = true; skipAuth: boolean = false; onComplete?: ( metadata: OnCompleteMetadata, cb: OnCompleteFinalCallback, ) => void | never; onError?: (error: GHRError) => void | never; constructor(options: GithubReleasesProviderOptions) { super(); const [owner, repo] = options.repository.split("/"); if (!owner || !repo) { const error = new GHRError( "repository must be in the format 'owner/repo'", 1, { repository: options.repository, }, ); this.onError?.(error); throw error; } this.owner = owner; this.repo = repo; this.destinationDir = options.destinationDir.replace("~", homedir()); ensureDirSync(this.destinationDir); this.osAssetMap = options.osAssetMap; if (options.displaySpinner === false) { this.displaySpinner = false; } if (options.prerelease === true) { this.prerelease = true; } this.skipAuth = !!options.skipAuth; const auth = this.skipAuth ? undefined : Deno.env.get("GITHUB_TOKEN") ?? Deno.env.get("GH_TOKEN"); this.octokit = new Octokit({ auth }); if (options.cleanupOld === false) { this.cleanupOld = false; } if (this.cleanupOld) { // triggering this in the provider constructor is somewhat gross // however it's the only way to ensure that the cleanup happens this.cleanOldVersions(); } this.onComplete = options?.onComplete || ((_meta: OnCompleteMetadata, _cb: OnCompleteFinalCallback) => {}); this.onError = options?.onError || ((_error: Error) => {}); } cleanOldVersions() { for (const entry of walkSync(this.destinationDir)) { if (entry.path.includes(OLD_VERSION_TAG)) { try { Deno.removeSync(entry.path); } catch (caught) { if (!(caught instanceof Deno.errors.NotFound)) { const foundButFailedToDelete = new GHRError( "Found old version but failed to delete", 2, { oldfile: entry.path, caught, }, ); this.onError?.(foundButFailedToDelete); throw foundButFailedToDelete; } } } } } getRepositoryUrl(_name: string): string { return `https://github.com/${this.owner}/${this.repo}/releases`; } getRegistryUrl(_name: string, version: string): string { return `https://github.com/${this.owner}/${this.repo}/releases/tag/${version}`; } getReleaseOctokitRequest(version: string): { path: string; opt: ReleaseParameters; } { return { path: `GET /repos/{owner}/{repo}/releases/tags/{tag}`, opt: { owner: this.owner, repo: this.repo, tag: version, }, }; } getOctokitAssetRequest(releaseResponse: ReleaseResponse): { path: string; opt: AssetParameters; } { const assetName = this.osAssetMap[Deno.build.os]; if (!assetName) { throw new GHRError("Failed to find asset name for current OS", 3, { os: Deno.build.os, osAssetMap: this.osAssetMap, }); } const asset = releaseResponse.data.assets.find( (asset: { name: string }) => asset.name === assetName, ); if (!asset) { throw new GHRError("Failed to find asset for current OS", 4, { os: Deno.build.os, assetName, assets: releaseResponse.data.assets, }); } const assetId = asset.id; // this url could be used with fetch() instead of octokit const _assetUrl = `https://api.github.com/repos/${this.owner}/${this.repo}/releases/assets/${assetId}`; return { path: `GET /repos/{owner}/{repo}/releases/assets/{asset_id}`, opt: { owner: this.owner, repo: this.repo, asset_id: assetId }, }; } // Add your custom code here //@ts-ignore - hotfix! async upgrade(options: GithubReleasesProviderUpgradeOptions): Promise<void> { let { name, from, to } = options; const os = Deno.build.os; const spinner = new Spinner({ message: `Upgrading ${colors.cyan(name)} from ${ colors.yellow( from || "?", ) } to version ${colors.cyan(to)}...`, color: "cyan", spinner: [ "▰▱▱▱▱▱▱", "▰▰▱▱▱▱▱", "▰▰▰▱▱▱▱", "▰▰▰▰▱▱▱", "▰▰▰▰▰▱▱", "▰▰▰▰▰▰▱", "▰▰▰▰▰▰▰", "▰▱▱▱▱▱▱", ], interval: 80, }); if (this.displaySpinner) { spinner.start(); } const versions = await this.getVersions(name); if (to === "latest") { to = versions.latest; } let response; // Wraps the Asset Data for inflate_response const stagingDir = Deno.makeTempDirSync(); let errorDetail = {}; if (this.skipAuth) { try { const assetName = this.osAssetMap[os]; if (!assetName) { const error = new GHRError( "Failed to find asset name for current OS", 3, { os, osAssetMap: this.osAssetMap, }, ); this.onError?.(error); throw error; } const url = `https://github.com/${this.owner}/${this.repo}/releases/download/${to}/${assetName}`; response = await fetch(url); errorDetail = { url, }; if (response.status !== 200) { throw new GHRError( "Failed to fetch GitHub Release Asset", parseInt(`5${response.status}`), { ...errorDetail, status: response.status, }, ); } } catch (caught) { const error = new GHRError( "Network Error: Failed to fetch GitHub Release Asset", 5, { ...errorDetail, caught, }, ); this.onError?.(error); throw error; } } else { const req = this.getReleaseOctokitRequest(to); let releaseResponse; // Release Metadata try { releaseResponse = await this.octokit.request(req.path, req.opt); } catch (errorFetching) { const error = new GHRError( "Failed to fetch Release metadata", // @ts-ignore - hotfix! parseInt(`5${errorFetching.status}`), { ...req, caught: errorFetching, }, ); this.onError?.(error); throw error; } const { path: assetReqPath, opt: assetReqOpt } = this .getOctokitAssetRequest( releaseResponse as ReleaseResponse, // if (releaseResponse.status === 200), this is safe ); let octokitAssetResponse; // Asset Data errorDetail = { assetReqPath, assetReqOpt, }; try { octokitAssetResponse = await this.octokit.request(assetReqPath, { ...assetReqOpt, headers: { Accept: "application/octet-stream", }, request: { responseType: "arraybuffer", }, }); // how costly is creating a Response? response = new Response(octokitAssetResponse.data, { status: octokitAssetResponse.status, }); } catch (errorFetching) { const error = new GHRError( "Failed to fetch GitHub Release Asset Data", //@ts-ignore - hotfix! parseInt(`6${errorFetching.status}`), { ...errorDetail, caught: errorFetching, }, ); this.onError?.(error); throw error; } } try { await inflateResponse(response, stagingDir, { compressionFormat: "gzip", doUntar: true, }); } catch (caught) { const error = new GHRError( `Failed to extract '${this.osAssetMap[os]}' archive`, 8, { caught, }, ); this.onError?.(error); throw error; } for (const entry of walkSync(stagingDir)) { if (entry.isFile) { const finalPath = entry.path.replace(stagingDir, this.destinationDir); try { // stash the old version Deno.renameSync(finalPath, `${finalPath}${OLD_VERSION_TAG}`); } catch (caught) { if (!(caught instanceof Deno.errors.NotFound)) { const error = new GHRError("Failed to stash old version", 9, { caught, oldfile: finalPath, }); this.onError?.(error); throw error; } } // install the new version try { Deno.renameSync(entry.path, finalPath); } catch (caught) { const error = new GHRError("Failed to install new version", 10, { caught, newfile: entry.path, }); this.onError?.(error); throw error; } if (os !== "windows") { Deno.chmodSync(finalPath, 0o755); } } } this?.onComplete?.({ to, from }, function printSuccessMessage() { spinner.stop(); const fromMsg = from ? ` from version ${colors.yellow(from)}` : ""; console.log( `Successfully upgraded ${ colors.cyan( name, ) }${fromMsg} to version ${colors.green(to)}!\n`, ); }); } async getVersions(_name: string): Promise<GithubReleaseVersions> { const url = `https://api.github.com/repos/${this.owner}/${this.repo}/releases`; let listReleasesResponse; try { listReleasesResponse = await this.octokit.request( "GET /repos/{owner}/{repo}/releases", { owner: this.owner, repo: this.repo, headers: { "X-GitHub-Api-Version": "2022-11-28", }, }, ); } catch (error) { //@ts-ignore - hotfix! const status = error.status; const getVersionsError = new GHRError( "Failed to octokit.request Release List from GitHub.", parseInt(`7${status}`), { status, caught: error, url, }, ); this.onError?.(getVersionsError); throw getVersionsError; } const versions = listReleasesResponse.data .filter((release) => { // never include draft releases if (release.draft) return false; // only include prereleases if the prerelease option is set to true if (release.prerelease) { if (this.prerelease) return true; // otherwise include all non-prerelease releases return false; } return true; }) .map(({ tag_name }) => tag_name) .sort(latestSemVerFirst); const latest = versions[0]; return { versions, // branches and tags latest, }; } //@ts-ignore hotfix! async listVersions( name: string, currentVersion?: string | undefined, ): Promise<void> { const { versions } = await this.getVersions(name); super.printVersions(versions, currentVersion, { indent: 0 }); } } interface GithubReleasesUpgradeOptions { provider: GithubReleasesProvider; } interface UpgradeActionOptions { force: boolean; verbose: boolean; version: string; to: string; from?: string; } const mutedLogger = { info: () => {}, error: () => {}, log: () => {}, warn: () => {}, }; /** * GithubReleasesUpgradeCommand * A Cliffy UpgradeCommand for upgrading software using GitHub Releases * @param options - An object containing the following properties: * - provider: A GithubReleasesProvider instance */ export class GithubReleasesUpgradeCommand extends UpgradeCommand { constructor(options: GithubReleasesUpgradeOptions) { const opt = { ...options, logger: mutedLogger }; super(opt); // assumes only one provider is passed into command constructor const provider: GithubReleasesProvider = Array.isArray(options.provider) ? options.provider[0] : options.provider; this.option( "--pre-release, --prerelease", "Include GitHub Releases marked pre-release", () => { if (provider instanceof GithubReleasesProvider) { provider.prerelease = true; } }, ); } }