import {Config, type Interfaces, ux} from '@oclif/core' import {green, yellow} from 'ansis' import makeDebug from 'debug' import fileSize from 'filesize' import {got, HTTPError} from 'got' import {existsSync, type Stats} from 'node:fs' import {mkdir, readdir, readFile, rm, stat, symlink, utimes, writeFile} from 'node:fs/promises' import {basename, dirname, join} from 'node:path' import {ProxyAgent} from 'proxy-agent' import {Extractor} from './tar.js' import {ls} from './util.js' const debug = makeDebug('oclif:update') const filesize = (n: number): string => { const [num, suffix] = fileSize(n, {output: 'array'}) return Number.parseFloat(num).toFixed(1) + ` ${suffix}` } async function httpGet(url: string) { debug(`[${url}] GET`) return got .get(url, { agent: {https: new ProxyAgent()}, }) .then((res) => { debug(`[${url}] ${res.statusCode}`) return res }) .catch((error) => { debug(`[${url}] ${error.response?.statusCode ?? error.code}`) // constructing a new HTTPError here will produce a more actionable stack trace debug(new HTTPError(error.response)) throw error }) } type Options = { autoUpdate: boolean channel?: string | undefined force?: boolean version?: string | undefined } type VersionIndex = Record export class Updater { private readonly clientBin: string private readonly clientRoot: string constructor(private config: Config) { this.clientRoot = config.scopedEnvVar('OCLIF_CLIENT_HOME') ?? join(config.dataDir, 'client') this.clientBin = join(this.clientRoot, 'bin', config.windows ? `${config.bin}.cmd` : config.bin) } public async fetchVersionIndex(): Promise { const newIndexUrl = this.config.s3Url(s3VersionIndexKey(this.config)) try { const {body} = await httpGet(newIndexUrl) return typeof body === 'string' ? JSON.parse(body) : body } catch { throw new Error(`No version indices exist for ${this.config.name}.`) } } public async findLocalVersions(): Promise { await ensureClientDir(this.clientRoot) const dirOrFiles = await readdir(this.clientRoot) return dirOrFiles .filter((dirOrFile) => dirOrFile !== 'bin' && dirOrFile !== 'current') .map((f) => join(this.clientRoot, f)) } public async runUpdate(options: Options): Promise { const {autoUpdate, force = false, version} = options if (autoUpdate) await debounce(this.config.cacheDir) ux.action.start(`${this.config.name}: Updating CLI`) if (notUpdatable(this.config)) { ux.action.stop('not updatable') return } const [channel, current] = await Promise.all([ options.channel ?? determineChannel({config: this.config, version}), determineCurrentVersion(this.clientBin, this.config.version), ]) if (version) { const localVersion = force ? undefined : await this.findLocalVersion(version) if (alreadyOnVersion(current, localVersion ?? undefined)) { ux.action.stop(this.config.scopedEnvVar('HIDE_UPDATED_MESSAGE') ? 'done' : `already on version ${current}`) return } await this.config.runHook('preupdate', {channel, version}) if (localVersion) { await this.updateToExistingVersion(current, localVersion) } else { ux.action.status = 'fetching version index' const index = await this.fetchVersionIndex() const url = index[version] if (!url) { throw new Error(`${version} not found in index:\n${Object.keys(index).join(', ')}`) } const manifest = await this.fetchVersionManifest(version, url) const updated = manifest.sha ? `${manifest.version}-${manifest.sha}` : manifest.version await this.update(manifest, current, updated, force, channel) } await this.config.runHook('update', {channel, version}) ux.action.stop() ux.stdout() ux.stdout( `Updating to a specific version will not update the channel. If autoupdate is enabled, the CLI will eventually be updated back to ${channel}.`, ) } else { const manifest = await fetchChannelManifest(channel, this.config) const updated = manifest.sha ? `${manifest.version}-${manifest.sha}` : manifest.version if (!force && alreadyOnVersion(current, updated)) { ux.action.stop(this.config.scopedEnvVar('HIDE_UPDATED_MESSAGE') ? 'done' : `already on version ${current}`) } else { await this.config.runHook('preupdate', {channel, version: updated}) await this.update(manifest, current, updated, force, channel) } await this.config.runHook('update', {channel, version: updated}) ux.action.stop() } await this.touch() await this.tidy() debug('done') } private async createBin(version: string): Promise { const dst = this.clientBin const {bin, windows} = this.config const binPathEnvVar = this.config.scopedEnvVarKey('BINPATH') const redirectedEnvVar = this.config.scopedEnvVarKey('REDIRECTED') await mkdir(dirname(dst), {recursive: true}) if (windows) { const body = `@echo off setlocal enableextensions set ${redirectedEnvVar}=1 set ${binPathEnvVar}=%~dp0${bin} "%~dp0..\\${version}\\bin\\${bin}.cmd" %* ` await writeFile(dst, body) } else { /* eslint-disable no-useless-escape */ const body = `#!/usr/bin/env bash set -e get_script_dir () { SOURCE="\${BASH_SOURCE[0]}" # While $SOURCE is a symlink, resolve it while [ -h "$SOURCE" ]; do DIR="$( cd -P "$( dirname "$SOURCE" )" && pwd )" SOURCE="$( readlink "$SOURCE" )" # If $SOURCE was a relative symlink (so no "/" as prefix, need to resolve it relative to the symlink base directory [[ $SOURCE != /* ]] && SOURCE="$DIR/$SOURCE" done DIR="$( cd -P "$( dirname "$SOURCE" )" && pwd )" echo "$DIR" } # Ensure everything is read at once before execution to avoid race conditions when updating versions { DIR=$(get_script_dir) ${binPathEnvVar}="\$DIR/${bin}" ${redirectedEnvVar}=1 "$DIR/../${version}/bin/${bin}" "$@" }; exit ` /* eslint-enable no-useless-escape */ await writeFile(dst, body, {mode: 0o755}) await rm(join(this.clientRoot, 'current'), {force: true, recursive: true}) await symlink(`./${version}`, join(this.clientRoot, 'current')) } } private async fetchVersionManifest(version: string, url: string): Promise { const parts = url.split('/') const hashIndex = parts.indexOf(version) + 1 const hash = parts[hashIndex] const s3Key = s3VersionManifestKey({config: this.config, hash, version}) return fetchManifest(s3Key, this.config) } private async findLocalVersion(version: string): Promise { const versions = await this.findLocalVersions() return versions.map((file) => basename(file)).find((file) => file.startsWith(version)) } private async refreshConfig(version: string): Promise { this.config = await Config.load({root: join(this.clientRoot, version)}) } // Resolves the absolute path of the active install directory. Installed // directories are named "-", but `this.config.version` is plain // semver, so match by exact name or "-" prefix. Falls back to the // bare version path when no match exists. private async resolveActiveDir(): Promise { const {version} = this.config try { const entries = await readdir(this.clientRoot) const match = entries.find((entry) => entry === version || entry.startsWith(`${version}-`)) if (match) return join(this.clientRoot, match) } catch { // fall through to bare version path } return join(this.clientRoot, version) } // removes any unused CLIs private async tidy(): Promise { debug('tidy') try { const root = this.clientRoot if (!existsSync(root)) return const files = await ls(root) // `version` is plain semver (e.g. "1.2.3") but installed directories are // named "-" (e.g. "1.2.3-abc1234"). Protect both forms so // the active CLI never deletes itself. See #1361. const isNotSpecial = (fPath: string, version: string): boolean => { const name = basename(fPath) if (name === 'bin' || name === 'current') return false // "1.2.3" or "1.2.3-abc1234" both start from `version` return !(name === version || name.startsWith(`${version}-`)) } const isOld = (fStat: Stats): boolean => { const {mtime} = fStat mtime.setHours(mtime.getHours() + 42 * 24) return mtime < new Date() } await Promise.all( files .filter((f) => isNotSpecial(f.path, this.config.version) && isOld(f.stat)) .map(async (f) => rm(f.path, {force: true, recursive: true})), ) } catch (error: unknown) { ux.warn(error as Error | string) } } private async touch(): Promise { // touch the client so it won't be tidied up right away try { // `this.config.version` is plain semver, but the installed directory is // named "-", so joining the bare version would point at a // non-existent path and silently no-op. Resolve the real directory the // same way tidy()'s guard does so the active install's mtime is refreshed // and it isn't considered "old". See #1361. const p = await this.resolveActiveDir() debug('touching client at', p) if (!existsSync(p)) return return utimes(p, new Date(), new Date()) } catch (error: unknown) { ux.warn(error as Error | string) } } // eslint-disable-next-line max-params private async update( manifest: Interfaces.S3Manifest, current: string, updated: string, force: boolean, channel: string, ) { ux.action.start( `${this.config.name}: Updating CLI from ${green(current)} to ${green(updated)}${ channel === 'stable' ? '' : ' (' + yellow(channel) + ')' }`, ) await ensureClientDir(this.clientRoot) const output = join(this.clientRoot, updated) if (force || !existsSync(output)) await downloadAndExtract(output, manifest, channel, this.config) await this.refreshConfig(updated) await setChannel(channel, this.config.dataDir) await this.createBin(updated) } private async updateToExistingVersion(current: string, updated: string): Promise { ux.action.start(`${this.config.name}: Updating CLI from ${green(current)} to ${green(updated)}`) await ensureClientDir(this.clientRoot) await this.refreshConfig(updated) await this.createBin(updated) } } const alreadyOnVersion = (current: string, updated?: string): boolean => current === updated const ensureClientDir = async (clientRoot: string): Promise => { try { await mkdir(clientRoot, {recursive: true}) } catch (error: unknown) { const {code} = error as {code: string} if (code === 'EEXIST') { // for some reason the client directory is sometimes a file // if so, this happens. Delete it and recreate await rm(clientRoot, {force: true, recursive: true}) await mkdir(clientRoot, {recursive: true}) } else { throw error } } } const mtime = async (f: string): Promise => (await stat(f)).mtime const notUpdatable = (config: Config): boolean => { if (!config.binPath) { const instructions = config.scopedEnvVar('UPDATE_INSTRUCTIONS') if (instructions) { ux.warn(instructions) // once the spinner stops, it'll eat this blank line // https://github.com/oclif/core/issues/799 ux.stdout() } return true } return false } const composeS3SubDir = (config: Config): string => { let s3SubDir = config.pjson.oclif.update?.s3?.folder || '' if (s3SubDir !== '' && !s3SubDir.endsWith('/')) s3SubDir = `${s3SubDir}/` return s3SubDir } const fetchManifest = async (s3Key: string, config: Config): Promise => { ux.action.status = 'fetching manifest' const url = config.s3Url(s3Key) const {body} = await httpGet(url) if (typeof body === 'string') { return JSON.parse(body) } return body } const s3VersionIndexKey = (config: Config): string => { const {arch, bin} = config const s3SubDir = composeS3SubDir(config) return join(s3SubDir, 'versions', `${bin}-${determinePlatform(config)}-${arch}-tar-gz.json`) } const determinePlatform = (config: Config): Interfaces.PlatformTypes => config.platform === 'wsl' ? 'linux' : config.platform const s3ChannelManifestKey = (channel: string, config: Config): string => { const {arch, bin} = config const s3SubDir = composeS3SubDir(config) return join(s3SubDir, 'channels', channel, `${bin}-${determinePlatform(config)}-${arch}-buildmanifest`) } const s3VersionManifestKey = ({config, hash, version}: {config: Config; hash: string; version: string}): string => { const {arch, bin} = config const s3SubDir = composeS3SubDir(config) return join( s3SubDir, 'versions', version, hash, `${bin}-v${version}-${hash}-${determinePlatform(config)}-${arch}-buildmanifest`, ) } // When autoupdating, wait until the CLI isn't active (lastrun mtime > 1 hour old). // // IMPORTANT: every CLI invocation touches lastrun before this function runs, so // while the user is actively using the CLI, `lastrun + 1hr` keeps shifting // forward and this wait never naturally resolves. The previous implementation // recursed forever in that scenario, leaving each spawned autoupdate child // pinned in memory as a full node process for the entire active session. When // combined with the race documented in hooks/init.ts (which could spawn // multiple such children per debounce window), the leaked children compounded // until OOM on machines doing heavy CLI setup. // // Fix: cap the wait at a sensible wall-clock max. If the user is still active // after that, abandon this autoupdate run — the next CLI invocation will fire // a new one when it's again "needed". const MAX_DEBOUNCE_WAIT_MS = 6 * 60 * 60 * 1000 // 6 hours const DEBOUNCE_POLL_INTERVAL_MS = 60 * 1000 // 1 minute const debounce = async (cacheDir: string): Promise => { const lastrunfile = join(cacheDir, 'lastrun') const startedAt = Date.now() let isAnnounced = false return new Promise((resolve) => { const check = async (): Promise => { const m = await mtime(lastrunfile) m.setHours(m.getHours() + 1) if (m <= new Date()) { ux.stdout('time to update') resolve() return } if (Date.now() - startedAt >= MAX_DEBOUNCE_WAIT_MS) { ux.stdout('autoupdate: debounce wait exceeded; abandoning this run') resolve() return } const msg = `waiting until ${m.toISOString()} to update` if (isAnnounced) { debug(msg) } else { ux.stdout(msg) isAnnounced = true } setTimeout(check, DEBOUNCE_POLL_INTERVAL_MS) } check() }) } const setChannel = async (channel: string, dataDir: string): Promise => writeFile(join(dataDir, 'channel'), channel, 'utf8') const fetchChannelManifest = async (channel: string, config: Config): Promise => { const s3Key = s3ChannelManifestKey(channel, config) try { return await fetchManifest(s3Key, config) } catch (error: unknown) { const {code, statusCode} = error as {code?: string; statusCode?: number} if (statusCode === 403 || code === 'ERR_NON_2XX_3XX_RESPONSE') throw new Error(`HTTP 403: Invalid channel ${channel}`) throw error } } const downloadAndExtract = async ( output: string, manifest: Interfaces.S3Manifest, channel: string, config: Config, ): Promise => { const {gz, sha256gz, version} = manifest const gzUrl = gz ?? config.s3Url( config.s3Key('versioned', { arch: config.arch, bin: config.bin, channel, ext: 'gz', platform: determinePlatform(config), version, }), ) debug(`Streaming ${gzUrl} to ${output}`) const stream = got.stream(gzUrl, { agent: {https: new ProxyAgent()}, }) stream.pause() const baseDir = manifest.baseDir ?? config.s3Key('baseDir', { arch: config.arch, bin: config.bin, channel, platform: determinePlatform(config), version, }) const extraction = Extractor.extract(stream, baseDir, output, sha256gz) if (ux.action.type === 'spinner') { stream.on('downloadProgress', (progress) => { ux.action.status = progress.percent === 1 ? `${filesize(progress.transferred)}/${filesize(progress?.total || 0)} - Finishing up...` : `${filesize(progress.transferred)}/${filesize(progress?.total || 0)}` }) } stream.resume() await extraction } const determineChannel = async ({config, version}: {config: Config; version?: string}): Promise => { ux.action.status = version ? `Determining channel for ${version}` : 'Determining channel' const channelPath = join(config.dataDir, 'channel') const channel = existsSync(channelPath) ? (await readFile(channelPath, 'utf8')).trim() : 'stable' if (config.pjson.oclif.update?.disableNpmLookup ?? false) { return channel } try { const {body} = await httpGet<{'dist-tags': Record}>( `${config.npmRegistry ?? 'https://registry.npmjs.org'}/${config.pjson.name}`, ) const tags = body['dist-tags'] const tag = Object.keys(tags).find((v) => tags[v] === version) ?? channel // convert from npm style tag defaults to OCLIF style if (tag === 'latest') return 'stable' if (tag === 'latest-rc') return 'stable-rc' return tag } catch { return channel } } const determineCurrentVersion = async (clientBin: string, version: string): Promise => { try { const currentVersion = await readFile(clientBin, 'utf8') const matches = /\.\.[/\\|](.+)[/\\|]bin/.exec(currentVersion) return matches ? matches[1] : version } catch (error) { if (error instanceof Error) { debug(error.name, error.message) } else if (typeof error === 'string') { debug(error) } } return version }