@flowscripter/dynamic-cli-framework 4.0.0 → 5.0.0

package/dist/src/command/VersionCommand.js

@@ -12,8 +12,8 @@ export default class VersionCommand {
         let line = context.cliConfig.version;
         if (context.doesServiceExist(UPGRADE_SERVICE_ID)) {
             const upgradeService = context.getServiceById(UPGRADE_SERVICE_ID);
-            const result = await upgradeService.getUpgradeCheckResult().catch(() => undefined);
-            if (result?.updateAvailable) {
+            const result = await upgradeService.getUpgradeCheckResult();
+            if (result.status === "checked" && result.updateAvailable) {
                 line += ` (${result.latestVersion} available, run '${context.cliConfig.name} upgrade')`;
             }
         }

package/dist/src/service/banner/BannerServiceProvider.js

@@ -52,8 +52,8 @@ export default class BannerServiceProvider {
         }
         if (context.doesServiceExist(UPGRADE_SERVICE_ID)) {
             const upgradeService = context.getServiceById(UPGRADE_SERVICE_ID);
-            const result = await upgradeService.getUpgradeCheckResult().catch(() => undefined);
-            if (result?.updateAvailable) {
+            const result = await upgradeService.getUpgradeCheckResult();
+            if (result.status === "checked" && result.updateAvailable) {
                 await printerService.info(`  ${printerService.secondary(`(${result.latestVersion} available, run '${cliConfig.name} upgrade')`)}\n`);
             }
         }

package/dist/src/service/upgrade/DefaultUpgradeService.d.ts

@@ -6,11 +6,11 @@ export default class DefaultUpgradeService implements UpgradeService {
     #private;
     constructor(config: UpgradeLocationsConfig, cliConfig: CLIConfig);
     setDependencies(spawnService: SpawnService | undefined, fetchService: FetchService | undefined): void;
-    getUpgradeCheckResult(waitForResult?: boolean): Promise<UpgradeCheckResult | undefined>;
+    getUpgradeCheckResult(waitForResult?: boolean): Promise<UpgradeCheckResult>;
     detectOs(): SupportedOs | undefined;
     detectArch(): SupportedArch | undefined;
     detectInstallMethod(os: SupportedOs): Promise<InstallMethod | undefined>;
-    checkForUpgrade(osOverride?: SupportedOs, archOverride?: SupportedArch, installMethodOverride?: InstallMethod): Promise<UpgradeCheckResult | undefined>;
+    checkForUpgrade(osOverride?: SupportedOs, archOverride?: SupportedArch, installMethodOverride?: InstallMethod): Promise<UpgradeCheckResult>;
     upgrade(osOverride?: SupportedOs, archOverride?: SupportedArch, installMethodOverride?: InstallMethod): Promise<UpgradeResult>;
 }
 //# sourceMappingURL=DefaultUpgradeService.d.ts.map

package/dist/src/service/upgrade/DefaultUpgradeService.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"DefaultUpgradeService.d.ts","sourceRoot":"","sources":["../../../../src/service/upgrade/DefaultUpgradeService.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EACV,SAAS,EACT,YAAY,EAEZ,YAAY,EACZ,kBAAkB,EAClB,aAAa,EACd,MAAM,yCAAyC,CAAC;AACjD,OAAO,EACL,aAAa,EACb,aAAa,EACb,WAAW,EACX,KAAK,cAAc,EACpB,MAAM,yCAAyC,CAAC;AAEjD,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,6BAA6B,CAAC;AAS1E,eAAO,MAAM,wBAAwB,MAAM,CAAC;AAc5C,MAAM,CAAC,OAAO,OAAO,qBAAsB,YAAW,cAAc;;gBAO/C,MAAM,EAAE,sBAAsB,EAAE,SAAS,EAAE,SAAS;IAKhE,eAAe,CACpB,YAAY,EAAE,YAAY,GAAG,SAAS,EACtC,YAAY,EAAE,YAAY,GAAG,SAAS,GACrC,IAAI;IAKA,qBAAqB,CAAC,aAAa,UAAQ,GAAG,OAAO,CAAC,kBAAkB,GAAG,SAAS,CAAC;IA0BrF,QAAQ,IAAI,WAAW,GAAG,SAAS;IAanC,UAAU,IAAI,aAAa,GAAG,SAAS;IAWjC,mBAAmB,CAAC,EAAE,EAAE,WAAW,GAAG,OAAO,CAAC,aAAa,GAAG,SAAS,CAAC;IAgBxE,eAAe,CAC1B,UAAU,CAAC,EAAE,WAAW,EACxB,YAAY,CAAC,EAAE,aAAa,EAC5B,qBAAqB,CAAC,EAAE,aAAa,GACpC,OAAO,CAAC,kBAAkB,GAAG,SAAS,CAAC;IAmC7B,OAAO,CAClB,UAAU,CAAC,EAAE,WAAW,EACxB,YAAY,CAAC,EAAE,aAAa,EAC5B,qBAAqB,CAAC,EAAE,aAAa,GACpC,OAAO,CAAC,aAAa,CAAC;CAoQ1B"}
+{"version":3,"file":"DefaultUpgradeService.d.ts","sourceRoot":"","sources":["../../../../src/service/upgrade/DefaultUpgradeService.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EACV,SAAS,EACT,YAAY,EAEZ,YAAY,EACZ,kBAAkB,EAClB,aAAa,EACd,MAAM,yCAAyC,CAAC;AACjD,OAAO,EACL,aAAa,EACb,aAAa,EACb,WAAW,EACX,KAAK,cAAc,EACpB,MAAM,yCAAyC,CAAC;AAEjD,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,6BAA6B,CAAC;AAM1E,eAAO,MAAM,wBAAwB,MAAM,CAAC;AAkB5C,MAAM,CAAC,OAAO,OAAO,qBAAsB,YAAW,cAAc;;gBAO/C,MAAM,EAAE,sBAAsB,EAAE,SAAS,EAAE,SAAS;IAKhE,eAAe,CACpB,YAAY,EAAE,YAAY,GAAG,SAAS,EACtC,YAAY,EAAE,YAAY,GAAG,SAAS,GACrC,IAAI;IAKA,qBAAqB,CAAC,aAAa,UAAQ,GAAG,OAAO,CAAC,kBAAkB,CAAC;IA0BzE,QAAQ,IAAI,WAAW,GAAG,SAAS;IAanC,UAAU,IAAI,aAAa,GAAG,SAAS;IAWjC,mBAAmB,CAAC,EAAE,EAAE,WAAW,GAAG,OAAO,CAAC,aAAa,GAAG,SAAS,CAAC;IAgBxE,eAAe,CAC1B,UAAU,CAAC,EAAE,WAAW,EACxB,YAAY,CAAC,EAAE,aAAa,EAC5B,qBAAqB,CAAC,EAAE,aAAa,GACpC,OAAO,CAAC,kBAAkB,CAAC;IAwCjB,OAAO,CAClB,UAAU,CAAC,EAAE,WAAW,EACxB,YAAY,CAAC,EAAE,aAAa,EAC5B,qBAAqB,CAAC,EAAE,aAAa,GACpC,OAAO,CAAC,aAAa,CAAC;CA4S1B"}

package/dist/src/service/upgrade/DefaultUpgradeService.js

@@ -4,8 +4,6 @@ import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { InstallMethod, SupportedArch, SupportedOs, } from "@flowscripter/dynamic-cli-framework-api";
 import semver from "semver";
-import getLogger from "../../util/logger.js";
-const logger = getLogger("DefaultUpgradeService");
 // checkForUpgrade() runs opportunistically on every CLI invocation (via BannerServiceProvider),
 // so that opportunistic call is raced against this timeout so it never stalls CLI startup.
 // A deliberate caller (waitForResult=true, e.g. the `upgrade` command) awaits checkForUpgrade()
@@ -37,14 +35,14 @@ export default class DefaultUpgradeService {
     }
     getUpgradeCheckResult(waitForResult = false) {
         if (!this.#upgradeCheckPromise) {
-            // Only cache a successful result. An `undefined` result can come from a transient
-            // failure (e.g. the opportunistic startup check racing past VERSION_CHECK_TIMEOUT_MS
-            // before checkForUpgrade() itself resolves) - caching that would permanently deny a
-            // later, deliberate caller (e.g. the `upgrade` command explicitly waiting via
-            // waitForResult=true) any chance of a fresh attempt for the rest of this process's
-            // lifetime.
+            // Only cache a non-"failed" result. A "failed" result can come from a transient issue
+            // (e.g. a network blip, or the opportunistic startup check racing past
+            // VERSION_CHECK_TIMEOUT_MS before checkForUpgrade() itself resolves) - caching that would
+            // permanently deny a later, deliberate caller (e.g. the `upgrade` command explicitly
+            // waiting via waitForResult=true) any chance of a fresh attempt for the rest of this
+            // process's lifetime.
             this.#upgradeCheckPromise = this.checkForUpgrade().then((result) => {
-                if (result === undefined) {
+                if (result.status === "failed") {
                     this.#upgradeCheckPromise = undefined;
                 }
                 return result;
@@ -55,7 +53,7 @@ export default class DefaultUpgradeService {
         }
         return Promise.race([
             this.#upgradeCheckPromise,
-            new Promise((resolve) => setTimeout(() => resolve(undefined), VERSION_CHECK_TIMEOUT_MS)),
+            new Promise((resolve) => setTimeout(() => resolve({ status: "pending" }), VERSION_CHECK_TIMEOUT_MS)),
         ]);
     }
     detectOs() {
@@ -99,26 +97,29 @@ export default class DefaultUpgradeService {
         const os = osOverride ?? this.detectOs();
         const arch = archOverride ?? this.detectArch();
         if (!os || !arch || !this.#isPlatformSupported(os, arch)) {
-            return undefined;
+            return { status: "unsupported" };
         }
         const installMethod = installMethodOverride ?? (await this.detectInstallMethod(os));
         if (!installMethod) {
-            return undefined;
+            return { status: "unsupported" };
         }
-        const latestVersion = await this.#getLatestVersion(installMethod);
-        if (!latestVersion) {
-            return undefined;
+        const versionLookup = await this.#getLatestVersion(installMethod);
+        if (!versionLookup.ok) {
+            return { status: "failed", error: versionLookup.error };
         }
         const currentVersion = this.#cliConfig.version;
         const coercedCurrent = semver.coerce(currentVersion);
-        const coercedLatest = semver.coerce(latestVersion);
+        const coercedLatest = semver.coerce(versionLookup.version);
         if (!coercedCurrent || !coercedLatest) {
-            logger.debug(() => `Unable to compare versions '${currentVersion}' and '${latestVersion}'`);
-            return undefined;
+            return {
+                status: "failed",
+                error: new Error(`Unable to compare versions '${currentVersion}' and '${versionLookup.version}'`),
+            };
         }
         return {
+            status: "checked",
             currentVersion,
-            latestVersion,
+            latestVersion: versionLookup.version,
             updateAvailable: semver.gt(coercedLatest, coercedCurrent),
             os,
             arch,
@@ -131,13 +132,20 @@ export default class DefaultUpgradeService {
         const checkResult = hasOverride
             ? await this.checkForUpgrade(osOverride, archOverride, installMethodOverride)
             : await this.getUpgradeCheckResult(true);
-        if (!checkResult) {
+        if (checkResult.status === "unsupported") {
             return {
                 ok: false,
                 oldVersion,
                 error: new Error("No upgrade location configured for the detected or requested platform"),
             };
         }
+        if (checkResult.status === "failed") {
+            return { ok: false, oldVersion, error: checkResult.error };
+        }
+        if (checkResult.status === "pending") {
+            // Unreachable: checkForUpgrade() and getUpgradeCheckResult(true) always run to completion.
+            return { ok: false, oldVersion, error: new Error("Upgrade check did not complete") };
+        }
         if (!this.#spawnService) {
             return { ok: false, oldVersion, error: new Error("SpawnService is not available") };
         }
@@ -194,53 +202,81 @@ export default class DefaultUpgradeService {
                 return this.#getLatestHomebrewVersion();
             case InstallMethod.WINGET:
                 return this.#getLatestWingetVersion();
-            default:
-                return undefined;
         }
     }
     async #getLatestGithubReleaseVersion() {
-        if (!this.#config.githubRelease || !this.#fetchService) {
-            return undefined;
+        if (!this.#config.githubRelease) {
+            return { ok: false, error: new Error("No githubRelease location configured") };
+        }
+        if (!this.#fetchService) {
+            return { ok: false, error: new Error("FetchService is not available") };
         }
         const { owner, repo } = this.#config.githubRelease;
         try {
-            const response = await this.#fetchService.fetch(`https://api.github.com/repos/${owner}/${repo}/releases/latest`);
-            if (!response.ok) {
-                return undefined;
+            // Uses the plain web redirect rather than the api.github.com REST endpoint, since the
+            // latter's unauthenticated rate limit (60 requests/hour/IP) is easily exhausted, e.g. by
+            // CI runners sharing an IP pool.
+            const response = await this.#fetchService.fetch(`https://github.com/${owner}/${repo}/releases/latest`, { redirect: "manual" });
+            const location = response.headers.get("location");
+            const version = location ? /\/releases\/tag\/v?([^/]+)$/.exec(location)?.[1] : undefined;
+            if (!version) {
+                return {
+                    ok: false,
+                    error: new Error(`Unexpected response resolving latest release for ${owner}/${repo}: HTTP ${response.status}`),
+                };
             }
-            const data = (await response.json());
-            return data.tag_name?.replace(/^v/, "");
+            return { ok: true, version };
         }
         catch (error) {
-            logger.debug(() => `Failed to fetch latest GitHub release for ${owner}/${repo}: ${error}`);
-            return undefined;
+            return {
+                ok: false,
+                error: new Error(`Failed to fetch latest GitHub release for ${owner}/${repo}: ${error}`),
+            };
         }
     }
     async #getLatestHomebrewVersion() {
-        if (!this.#config.homebrew || !this.#fetchService) {
-            return undefined;
+        if (!this.#config.homebrew) {
+            return { ok: false, error: new Error("No homebrew location configured") };
+        }
+        if (!this.#fetchService) {
+            return { ok: false, error: new Error("FetchService is not available") };
         }
         const { tap, formula } = this.#config.homebrew;
         const [tapOwner, tapName] = tap.split("/");
         if (!tapOwner || !tapName) {
-            return undefined;
+            return { ok: false, error: new Error(`Invalid homebrew tap '${tap}'`) };
         }
         try {
             const response = await this.#fetchService.fetch(`https://raw.githubusercontent.com/${tapOwner}/homebrew-${tapName}/main/${formula}.rb`);
             if (!response.ok) {
-                return undefined;
+                return {
+                    ok: false,
+                    error: new Error(`Failed to fetch homebrew formula for ${tap}/${formula}: HTTP ${response.status}`),
+                };
             }
             const text = await response.text();
-            return /version\s+"v?([^"]+)"/.exec(text)?.[1];
+            const version = /version\s+"v?([^"]+)"/.exec(text)?.[1];
+            if (!version) {
+                return {
+                    ok: false,
+                    error: new Error(`Could not parse version from homebrew formula ${tap}/${formula}`),
+                };
+            }
+            return { ok: true, version };
         }
         catch (error) {
-            logger.debug(() => `Failed to fetch homebrew formula for ${tap}/${formula}: ${error}`);
-            return undefined;
+            return {
+                ok: false,
+                error: new Error(`Failed to fetch homebrew formula for ${tap}/${formula}: ${error}`),
+            };
         }
     }
     async #getLatestWingetVersion() {
-        if (!this.#spawnService || !this.#config.winget) {
-            return undefined;
+        if (!this.#config.winget) {
+            return { ok: false, error: new Error("No winget location configured") };
+        }
+        if (!this.#spawnService) {
+            return { ok: false, error: new Error("SpawnService is not available") };
         }
         const lines = [];
         const result = await this.#spawnService.spawn(["winget", "show", "--id", this.#config.winget.packageId], {
@@ -249,15 +285,15 @@ export default class DefaultUpgradeService {
             onOutput: (line) => lines.push(line),
         });
         if (!result.ok) {
-            return undefined;
+            return { ok: false, error: new Error(`winget show failed: ${describeSpawnFailure(result)}`) };
         }
         for (const line of lines) {
             const match = /Version:\s*(\S+)/.exec(line);
             if (match?.[1]) {
-                return match[1];
+                return { ok: true, version: match[1] };
             }
         }
-        return undefined;
+        return { ok: false, error: new Error("Could not parse version from winget output") };
     }
     async #upgradeViaLinuxScript() {
         const { scriptUrl } = this.#config.linuxScript;

package/dist/src/service/upgrade/UpgradeServiceProvider.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"UpgradeServiceProvider.d.ts","sourceRoot":"","sources":["../../../../src/service/upgrade/UpgradeServiceProvider.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,yCAAyC,CAAC;AAC5F,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,yCAAyC,CAAC;AACvE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAczE,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,6BAA6B,CAAC;AAK1E,MAAM,CAAC,OAAO,OAAO,sBAAuB,YAAW,eAAe;;IACpE,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAsB;IAChD,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;gBAKd,eAAe,EAAE,MAAM,EAAE,MAAM,EAAE,sBAAsB;IAKnE,cAAc,CAAC,SAAS,EAAE,SAAS,GAAG,OAAO,CAAC,WAAW,CAAC;IASpD,WAAW,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC;CAsH1D"}
+{"version":3,"file":"UpgradeServiceProvider.d.ts","sourceRoot":"","sources":["../../../../src/service/upgrade/UpgradeServiceProvider.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,yCAAyC,CAAC;AAC5F,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,yCAAyC,CAAC;AACvE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAczE,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,6BAA6B,CAAC;AAK1E,MAAM,CAAC,OAAO,OAAO,sBAAuB,YAAW,eAAe;;IACpE,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAsB;IAChD,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;gBAKd,eAAe,EAAE,MAAM,EAAE,MAAM,EAAE,sBAAsB;IAKnE,cAAc,CAAC,SAAS,EAAE,SAAS,GAAG,OAAO,CAAC,WAAW,CAAC;IASpD,WAAW,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC;CA0H1D"}

package/dist/src/service/upgrade/UpgradeServiceProvider.js

@@ -106,7 +106,11 @@ export default class UpgradeServiceProvider {
     async #checkAndUpgrade(context, upgradeService, cliConfig) {
         try {
             const checkResult = await upgradeService.getUpgradeCheckResult();
-            if (!checkResult?.updateAvailable) {
+            if (checkResult.status === "failed") {
+                logger.debug(() => `Auto-upgrade check failed: ${checkResult.error.message}`);
+                return;
+            }
+            if (checkResult.status !== "checked" || !checkResult.updateAvailable) {
                 return;
             }
             const upgradeResult = await upgradeService.upgrade();

package/dist/src/service/upgrade/command/UpgradeSubCommand.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"UpgradeSubCommand.d.ts","sourceRoot":"","sources":["../../../../../src/service/upgrade/command/UpgradeSubCommand.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,yCAAyC,CAAC;AAC1E,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,yCAAyC,CAAC;AACtE,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,yCAAyC,CAAC;AACvE,OAAO,EAAE,KAAK,MAAM,EAAiB,MAAM,yCAAyC,CAAC;AASrF,OAAO,KAAK,qBAAqB,MAAM,6BAA6B,CAAC;AAErE,qBAAa,iBAAkB,YAAW,UAAU;;IAClD,QAAQ,CAAC,IAAI,aAAa;IAC1B,QAAQ,CAAC,WAAW,6CAA6C;IACjE,QAAQ,CAAC,mBAAmB,SAAS;IACrC,QAAQ,CAAC,WAAW,UAAM;IAE1B,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAC,MAAM,CAAC,CAerC;gBAIiB,cAAc,EAAE,qBAAqB;IAI3C,OAAO,CAAC,OAAO,EAAE,OAAO,EAAE,cAAc,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAyC9E"}
+{"version":3,"file":"UpgradeSubCommand.d.ts","sourceRoot":"","sources":["../../../../../src/service/upgrade/command/UpgradeSubCommand.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,yCAAyC,CAAC;AAC1E,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,yCAAyC,CAAC;AACtE,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,yCAAyC,CAAC;AACvE,OAAO,EAAE,KAAK,MAAM,EAAiB,MAAM,yCAAyC,CAAC;AASrF,OAAO,KAAK,qBAAqB,MAAM,6BAA6B,CAAC;AAErE,qBAAa,iBAAkB,YAAW,UAAU;;IAClD,QAAQ,CAAC,IAAI,aAAa;IAC1B,QAAQ,CAAC,WAAW,6CAA6C;IACjE,QAAQ,CAAC,mBAAmB,SAAS;IACrC,QAAQ,CAAC,WAAW,UAAM;IAE1B,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAC,MAAM,CAAC,CAerC;gBAIiB,cAAc,EAAE,qBAAqB;IAI3C,OAAO,CAAC,OAAO,EAAE,OAAO,EAAE,cAAc,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAuD9E"}

package/dist/src/service/upgrade/command/UpgradeSubCommand.js

@@ -34,10 +34,19 @@ export class UpgradeSubCommand {
         const checkResult = os === undefined && installMethod === undefined
             ? await this.#upgradeService.getUpgradeCheckResult(true)
             : await this.#upgradeService.checkForUpgrade(os, arch, installMethod);
-        if (!checkResult) {
+        if (checkResult.status === "unsupported") {
             await printerService.error(`No upgrade location is configured for the detected or requested platform.\n`, Icon.FAILURE);
             return;
         }
+        if (checkResult.status === "failed") {
+            await printerService.error(`Failed to check for updates: ${checkResult.error.message}. Please try again later.\n`, Icon.FAILURE);
+            return;
+        }
+        if (checkResult.status === "pending") {
+            // Unreachable: getUpgradeCheckResult(true) and checkForUpgrade() always run to completion.
+            await printerService.error(`Failed to check for updates.\n`, Icon.FAILURE);
+            return;
+        }
         if (!checkResult.updateAvailable) {
             await printerService.print(`${cliName} is already up to date (${checkResult.currentVersion}).\n`);
             return;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flowscripter/dynamic-cli-framework",
-  "version": "4.0.0",
+  "version": "5.0.0",
   "description": "A framework for developing CLI applications which supports dynamic discovery and installation of new commands",
   "keywords": [
     "bun",
@@ -48,7 +48,7 @@
     "build": "tsc -p tsconfig.build.json"
   },
   "dependencies": {
-    "@flowscripter/dynamic-cli-framework-api": "^1.5.0",
+    "@flowscripter/dynamic-cli-framework-api": "^2.0.0",
     "@flowscripter/dynamic-plugin-framework": "2.0.0",
     "emphasize": "^7.0.0",
     "fastest-levenshtein": "^1.0.16",

package/src/command/VersionCommand.ts

@@ -19,8 +19,8 @@ export default class VersionCommand implements GlobalCommand {
     let line = context.cliConfig.version;
     if (context.doesServiceExist(UPGRADE_SERVICE_ID)) {
       const upgradeService = context.getServiceById(UPGRADE_SERVICE_ID) as UpgradeService;
-      const result = await upgradeService.getUpgradeCheckResult().catch(() => undefined);
-      if (result?.updateAvailable) {
+      const result = await upgradeService.getUpgradeCheckResult();
+      if (result.status === "checked" && result.updateAvailable) {
         line += ` (${result.latestVersion} available, run '${context.cliConfig.name} upgrade')`;
       }
     }

package/src/service/banner/BannerServiceProvider.ts

@@ -72,8 +72,8 @@ export default class BannerServiceProvider implements ServiceProvider {
     }
     if (context.doesServiceExist(UPGRADE_SERVICE_ID)) {
       const upgradeService = context.getServiceById(UPGRADE_SERVICE_ID) as UpgradeService;
-      const result = await upgradeService.getUpgradeCheckResult().catch(() => undefined);
-      if (result?.updateAvailable) {
+      const result = await upgradeService.getUpgradeCheckResult();
+      if (result.status === "checked" && result.updateAvailable) {
         await printerService.info(
           `  ${printerService.secondary(
             `(${result.latestVersion} available, run '${cliConfig.name} upgrade')`,

package/src/service/upgrade/DefaultUpgradeService.ts

@@ -18,9 +18,6 @@ import {
 } from "@flowscripter/dynamic-cli-framework-api";
 import semver from "semver";
 import type { UpgradeLocationsConfig } from "./UpgradeLocationsConfig.ts";
-import getLogger from "../../util/logger.ts";
-
-const logger = getLogger("DefaultUpgradeService");
 
 // checkForUpgrade() runs opportunistically on every CLI invocation (via BannerServiceProvider),
 // so that opportunistic call is raced against this timeout so it never stalls CLI startup.
@@ -28,6 +25,10 @@ const logger = getLogger("DefaultUpgradeService");
 // directly with no timeout, so its underlying network/spawn calls are never artificially cut off.
 export const VERSION_CHECK_TIMEOUT_MS = 250;
 
+type VersionLookupResult =
+  | { readonly ok: true; readonly version: string }
+  | { readonly ok: false; readonly error: Error };
+
 function describeSpawnFailure(result: Extract<SpawnResult, { ok: false }>): string {
   return "timedOut" in result
     ? "timed out"
@@ -43,7 +44,7 @@ const OS_LABELS: Record<SupportedOs, string> = {
 export default class DefaultUpgradeService implements UpgradeService {
   #spawnService: SpawnService | undefined;
   #fetchService: FetchService | undefined;
-  #upgradeCheckPromise: Promise<UpgradeCheckResult | undefined> | undefined;
+  #upgradeCheckPromise: Promise<UpgradeCheckResult> | undefined;
   readonly #config: UpgradeLocationsConfig;
   readonly #cliConfig: CLIConfig;
 
@@ -60,16 +61,16 @@ export default class DefaultUpgradeService implements UpgradeService {
     this.#fetchService = fetchService;
   }
 
-  public getUpgradeCheckResult(waitForResult = false): Promise<UpgradeCheckResult | undefined> {
+  public getUpgradeCheckResult(waitForResult = false): Promise<UpgradeCheckResult> {
     if (!this.#upgradeCheckPromise) {
-      // Only cache a successful result. An `undefined` result can come from a transient
-      // failure (e.g. the opportunistic startup check racing past VERSION_CHECK_TIMEOUT_MS
-      // before checkForUpgrade() itself resolves) - caching that would permanently deny a
-      // later, deliberate caller (e.g. the `upgrade` command explicitly waiting via
-      // waitForResult=true) any chance of a fresh attempt for the rest of this process's
-      // lifetime.
+      // Only cache a non-"failed" result. A "failed" result can come from a transient issue
+      // (e.g. a network blip, or the opportunistic startup check racing past
+      // VERSION_CHECK_TIMEOUT_MS before checkForUpgrade() itself resolves) - caching that would
+      // permanently deny a later, deliberate caller (e.g. the `upgrade` command explicitly
+      // waiting via waitForResult=true) any chance of a fresh attempt for the rest of this
+      // process's lifetime.
       this.#upgradeCheckPromise = this.checkForUpgrade().then((result) => {
-        if (result === undefined) {
+        if (result.status === "failed") {
           this.#upgradeCheckPromise = undefined;
         }
         return result;
@@ -80,8 +81,8 @@ export default class DefaultUpgradeService implements UpgradeService {
     }
     return Promise.race([
       this.#upgradeCheckPromise,
-      new Promise<undefined>((resolve) =>
-        setTimeout(() => resolve(undefined), VERSION_CHECK_TIMEOUT_MS),
+      new Promise<UpgradeCheckResult>((resolve) =>
+        setTimeout(() => resolve({ status: "pending" }), VERSION_CHECK_TIMEOUT_MS),
       ),
     ]);
   }
@@ -130,34 +131,39 @@ export default class DefaultUpgradeService implements UpgradeService {
     osOverride?: SupportedOs,
     archOverride?: SupportedArch,
     installMethodOverride?: InstallMethod,
-  ): Promise<UpgradeCheckResult | undefined> {
+  ): Promise<UpgradeCheckResult> {
     const os = osOverride ?? this.detectOs();
     const arch = archOverride ?? this.detectArch();
     if (!os || !arch || !this.#isPlatformSupported(os, arch)) {
-      return undefined;
+      return { status: "unsupported" };
     }
 
     const installMethod = installMethodOverride ?? (await this.detectInstallMethod(os));
     if (!installMethod) {
-      return undefined;
+      return { status: "unsupported" };
     }
 
-    const latestVersion = await this.#getLatestVersion(installMethod);
-    if (!latestVersion) {
-      return undefined;
+    const versionLookup = await this.#getLatestVersion(installMethod);
+    if (!versionLookup.ok) {
+      return { status: "failed", error: versionLookup.error };
     }
 
     const currentVersion = this.#cliConfig.version;
     const coercedCurrent = semver.coerce(currentVersion);
-    const coercedLatest = semver.coerce(latestVersion);
+    const coercedLatest = semver.coerce(versionLookup.version);
     if (!coercedCurrent || !coercedLatest) {
-      logger.debug(() => `Unable to compare versions '${currentVersion}' and '${latestVersion}'`);
-      return undefined;
+      return {
+        status: "failed",
+        error: new Error(
+          `Unable to compare versions '${currentVersion}' and '${versionLookup.version}'`,
+        ),
+      };
     }
 
     return {
+      status: "checked",
       currentVersion,
-      latestVersion,
+      latestVersion: versionLookup.version,
       updateAvailable: semver.gt(coercedLatest, coercedCurrent),
       os,
       arch,
@@ -176,13 +182,20 @@ export default class DefaultUpgradeService implements UpgradeService {
     const checkResult = hasOverride
       ? await this.checkForUpgrade(osOverride, archOverride, installMethodOverride)
       : await this.getUpgradeCheckResult(true);
-    if (!checkResult) {
+    if (checkResult.status === "unsupported") {
       return {
         ok: false,
         oldVersion,
         error: new Error("No upgrade location configured for the detected or requested platform"),
       };
     }
+    if (checkResult.status === "failed") {
+      return { ok: false, oldVersion, error: checkResult.error };
+    }
+    if (checkResult.status === "pending") {
+      // Unreachable: checkForUpgrade() and getUpgradeCheckResult(true) always run to completion.
+      return { ok: false, oldVersion, error: new Error("Upgrade check did not complete") };
+    }
     if (!this.#spawnService) {
       return { ok: false, oldVersion, error: new Error("SpawnService is not available") };
     }
@@ -243,7 +256,7 @@ export default class DefaultUpgradeService implements UpgradeService {
     return process.execPath.startsWith("/usr/local/bin/");
   }
 
-  async #getLatestVersion(installMethod: InstallMethod): Promise<string | undefined> {
+  async #getLatestVersion(installMethod: InstallMethod): Promise<VersionLookupResult> {
     switch (installMethod) {
       case InstallMethod.GITHUB_RELEASE:
       case InstallMethod.LINUX_SCRIPT:
@@ -252,58 +265,91 @@ export default class DefaultUpgradeService implements UpgradeService {
         return this.#getLatestHomebrewVersion();
       case InstallMethod.WINGET:
         return this.#getLatestWingetVersion();
-      default:
-        return undefined;
     }
   }
 
-  async #getLatestGithubReleaseVersion(): Promise<string | undefined> {
-    if (!this.#config.githubRelease || !this.#fetchService) {
-      return undefined;
+  async #getLatestGithubReleaseVersion(): Promise<VersionLookupResult> {
+    if (!this.#config.githubRelease) {
+      return { ok: false, error: new Error("No githubRelease location configured") };
+    }
+    if (!this.#fetchService) {
+      return { ok: false, error: new Error("FetchService is not available") };
     }
     const { owner, repo } = this.#config.githubRelease;
     try {
+      // Uses the plain web redirect rather than the api.github.com REST endpoint, since the
+      // latter's unauthenticated rate limit (60 requests/hour/IP) is easily exhausted, e.g. by
+      // CI runners sharing an IP pool.
       const response = await this.#fetchService.fetch(
-        `https://api.github.com/repos/${owner}/${repo}/releases/latest`,
+        `https://github.com/${owner}/${repo}/releases/latest`,
+        { redirect: "manual" },
       );
-      if (!response.ok) {
-        return undefined;
+      const location = response.headers.get("location");
+      const version = location ? /\/releases\/tag\/v?([^/]+)$/.exec(location)?.[1] : undefined;
+      if (!version) {
+        return {
+          ok: false,
+          error: new Error(
+            `Unexpected response resolving latest release for ${owner}/${repo}: HTTP ${response.status}`,
+          ),
+        };
       }
-      const data = (await response.json()) as { tag_name?: string };
-      return data.tag_name?.replace(/^v/, "");
+      return { ok: true, version };
     } catch (error) {
-      logger.debug(() => `Failed to fetch latest GitHub release for ${owner}/${repo}: ${error}`);
-      return undefined;
+      return {
+        ok: false,
+        error: new Error(`Failed to fetch latest GitHub release for ${owner}/${repo}: ${error}`),
+      };
     }
   }
 
-  async #getLatestHomebrewVersion(): Promise<string | undefined> {
-    if (!this.#config.homebrew || !this.#fetchService) {
-      return undefined;
+  async #getLatestHomebrewVersion(): Promise<VersionLookupResult> {
+    if (!this.#config.homebrew) {
+      return { ok: false, error: new Error("No homebrew location configured") };
+    }
+    if (!this.#fetchService) {
+      return { ok: false, error: new Error("FetchService is not available") };
     }
     const { tap, formula } = this.#config.homebrew;
     const [tapOwner, tapName] = tap.split("/");
     if (!tapOwner || !tapName) {
-      return undefined;
+      return { ok: false, error: new Error(`Invalid homebrew tap '${tap}'`) };
     }
     try {
       const response = await this.#fetchService.fetch(
         `https://raw.githubusercontent.com/${tapOwner}/homebrew-${tapName}/main/${formula}.rb`,
       );
       if (!response.ok) {
-        return undefined;
+        return {
+          ok: false,
+          error: new Error(
+            `Failed to fetch homebrew formula for ${tap}/${formula}: HTTP ${response.status}`,
+          ),
+        };
       }
       const text = await response.text();
-      return /version\s+"v?([^"]+)"/.exec(text)?.[1];
+      const version = /version\s+"v?([^"]+)"/.exec(text)?.[1];
+      if (!version) {
+        return {
+          ok: false,
+          error: new Error(`Could not parse version from homebrew formula ${tap}/${formula}`),
+        };
+      }
+      return { ok: true, version };
     } catch (error) {
-      logger.debug(() => `Failed to fetch homebrew formula for ${tap}/${formula}: ${error}`);
-      return undefined;
+      return {
+        ok: false,
+        error: new Error(`Failed to fetch homebrew formula for ${tap}/${formula}: ${error}`),
+      };
     }
   }
 
-  async #getLatestWingetVersion(): Promise<string | undefined> {
-    if (!this.#spawnService || !this.#config.winget) {
-      return undefined;
+  async #getLatestWingetVersion(): Promise<VersionLookupResult> {
+    if (!this.#config.winget) {
+      return { ok: false, error: new Error("No winget location configured") };
+    }
+    if (!this.#spawnService) {
+      return { ok: false, error: new Error("SpawnService is not available") };
     }
     const lines: string[] = [];
     const result = await this.#spawnService.spawn(
@@ -315,15 +361,15 @@ export default class DefaultUpgradeService implements UpgradeService {
       },
     );
     if (!result.ok) {
-      return undefined;
+      return { ok: false, error: new Error(`winget show failed: ${describeSpawnFailure(result)}`) };
     }
     for (const line of lines) {
       const match = /Version:\s*(\S+)/.exec(line);
       if (match?.[1]) {
-        return match[1];
+        return { ok: true, version: match[1] };
       }
     }
-    return undefined;
+    return { ok: false, error: new Error("Could not parse version from winget output") };
   }
 
   async #upgradeViaLinuxScript(): Promise<void> {

package/src/service/upgrade/UpgradeServiceProvider.ts

@@ -135,7 +135,11 @@ export default class UpgradeServiceProvider implements ServiceProvider {
   ): Promise<void> {
     try {
       const checkResult = await upgradeService.getUpgradeCheckResult();
-      if (!checkResult?.updateAvailable) {
+      if (checkResult.status === "failed") {
+        logger.debug(() => `Auto-upgrade check failed: ${checkResult.error.message}`);
+        return;
+      }
+      if (checkResult.status !== "checked" || !checkResult.updateAvailable) {
         return;
       }
       const upgradeResult = await upgradeService.upgrade();

package/src/service/upgrade/command/UpgradeSubCommand.ts

@@ -53,7 +53,7 @@ export class UpgradeSubCommand implements SubCommand {
       os === undefined && installMethod === undefined
         ? await this.#upgradeService.getUpgradeCheckResult(true)
         : await this.#upgradeService.checkForUpgrade(os, arch, installMethod);
-    if (!checkResult) {
+    if (checkResult.status === "unsupported") {
       await printerService.error(
         `No upgrade location is configured for the detected or requested platform.\n`,
         Icon.FAILURE,
@@ -61,6 +61,20 @@ export class UpgradeSubCommand implements SubCommand {
       return;
     }
 
+    if (checkResult.status === "failed") {
+      await printerService.error(
+        `Failed to check for updates: ${checkResult.error.message}. Please try again later.\n`,
+        Icon.FAILURE,
+      );
+      return;
+    }
+
+    if (checkResult.status === "pending") {
+      // Unreachable: getUpgradeCheckResult(true) and checkForUpgrade() always run to completion.
+      await printerService.error(`Failed to check for updates.\n`, Icon.FAILURE);
+      return;
+    }
+
     if (!checkResult.updateAvailable) {
       await printerService.print(
         `${cliName} is already up to date (${checkResult.currentVersion}).\n`,