@flowscripter/dynamic-cli-framework 6.0.1 → 7.0.0

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

@@ -1,16 +1,32 @@
 import process from "node:process";
+import { realpathSync } from "node:fs";
 import { mkdtemp, rename, rm } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { dirname, join } from "node:path";
-import { InstallMethod, SupportedArch, SupportedOs, } from "@flowscripter/dynamic-cli-framework-api";
+import { FETCH_SERVICE_ID, InstallMethod, KEY_VALUE_SERVICE_ID, PRINTER_SERVICE_ID, SPAWN_SERVICE_ID, 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()
-// directly with no timeout, so its underlying network/spawn calls are never artificially cut off.
-export const VERSION_CHECK_TIMEOUT_MS = 250;
+// KeyValueService key caching the resolved InstallMethod (see detectInstallMethod()). Stored
+// value shape: { method: InstallMethod, checkedAt: number } where checkedAt is Date.now() at
+// detection time - refreshed on the same CACHE_TTL_MILLIS cycle as the latest-version cache below,
+// rather than trusted indefinitely, so a reinstall via a different method is eventually picked up
+// even outside the no-spawn signals (Cellar path, linux script prefix) that self-heal immediately.
+const INSTALL_METHOD_CACHE_KEY = "install-method";
+// KeyValueService key prefix caching a #getLatestVersion() lookup per install method, e.g.
+// "latest-version:homebrew". Stored value shape: { version: string, checkedAt: number } where
+// checkedAt is Date.now() at lookup time - see CACHE_TTL_MILLIS.
+const LATEST_VERSION_CACHE_KEY_PREFIX = "latest-version:";
+// How long a cached install-method or latest-version lookup is trusted before a fresh
+// spawn/network lookup runs again - long enough to remove the cost from routine invocations,
+// short enough that a genuine reinstall or new release surfaces within about a day.
+const CACHE_TTL_MILLIS = 24 * 60 * 60 * 1000;
+// KeyValueService key holding the last checkForUpgrade() result, refreshed opportunistically by
+// UpgradeServiceProvider's background StartupTask and by the `upgrade` command - shared by both so
+// there's one cache, not two. The banner task only ever reads this key (kv.has()/kv.get()) - it
+// never calls checkForUpgrade()/getUpgradeCheckResult() live, since checking live would stall
+// startup on the network/spawn calls checkForUpgrade() makes.
+export const UPGRADE_CHECK_CACHE_KEY = "upgrade-check-result";
 function describeSpawnFailure(result) {
     return "timedOut" in result
         ? "timed out"
@@ -27,9 +43,7 @@ const OS_LABELS = {
     [SupportedOs.WINDOWS]: "Windows",
 };
 export default class DefaultUpgradeService {
-    #spawnService;
-    #fetchService;
-    #printerService;
+    #context;
     #upgradeCheckPromise;
     #config;
     #cliConfig;
@@ -37,10 +51,28 @@ export default class DefaultUpgradeService {
         this.#config = config;
         this.#cliConfig = cliConfig;
     }
-    setDependencies(spawnService, fetchService, printerService) {
-        this.#spawnService = spawnService;
-        this.#fetchService = fetchService;
-        this.#printerService = printerService;
+    setContext(context) {
+        this.#context = context;
+    }
+    get #spawnService() {
+        return this.#context?.doesServiceExist(SPAWN_SERVICE_ID)
+            ? this.#context.getServiceById(SPAWN_SERVICE_ID)
+            : undefined;
+    }
+    get #fetchService() {
+        return this.#context?.doesServiceExist(FETCH_SERVICE_ID)
+            ? this.#context.getServiceById(FETCH_SERVICE_ID)
+            : undefined;
+    }
+    get #printerService() {
+        return this.#context?.doesServiceExist(PRINTER_SERVICE_ID)
+            ? this.#context.getServiceById(PRINTER_SERVICE_ID)
+            : undefined;
+    }
+    get #keyValueService() {
+        return this.#context?.doesServiceExist(KEY_VALUE_SERVICE_ID)
+            ? this.#context.getServiceById(KEY_VALUE_SERVICE_ID)
+            : undefined;
     }
     // Mirrors SpawnInterfaceAdapter's plugin:add/plugin:remove pattern: wrap a spawned command's
     // output in a quoted, marked block that's cleared on success (so a clean install stays quiet)
@@ -72,15 +104,12 @@ export default class DefaultUpgradeService {
         }
         return result;
     }
-    getUpgradeCheckResult(waitForResult = false) {
+    getUpgradeCheckResult() {
         if (!this.#upgradeCheckPromise) {
             logger.debug(() => "Starting upgrade check");
             // 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.
+            // (e.g. a network blip) - caching that would permanently deny a later caller any chance of
+            // a fresh attempt for the rest of this process's lifetime.
             this.#upgradeCheckPromise = this.checkForUpgrade().then((result) => {
                 logger.debug(() => describeUpgradeCheckResult(result));
                 if (result.status === "failed") {
@@ -89,13 +118,20 @@ export default class DefaultUpgradeService {
                 return result;
             });
         }
-        if (waitForResult) {
-            return this.#upgradeCheckPromise;
+        return this.#upgradeCheckPromise;
+    }
+    /**
+     * Run (or reuse an in-flight/cached) {@link getUpgradeCheckResult}, then persist a "checked" or
+     * "unsupported" result to {@link UPGRADE_CHECK_CACHE_KEY} so the banner task's cheap KV read can
+     * pick it up on a later invocation.
+     */
+    async refreshUpgradeCheckCache() {
+        const result = await this.getUpgradeCheckResult();
+        if (this.#keyValueService && (result.status === "checked" || result.status === "unsupported")) {
+            const keyValueService = this.#keyValueService;
+            await this.#safeKeyValueCall(() => keyValueService.set(UPGRADE_CHECK_CACHE_KEY, result));
         }
-        return Promise.race([
-            this.#upgradeCheckPromise,
-            new Promise((resolve) => setTimeout(() => resolve({ status: "pending" }), VERSION_CHECK_TIMEOUT_MS)),
-        ]);
+        return result;
     }
     detectOs() {
         switch (process.platform) {
@@ -120,19 +156,73 @@ export default class DefaultUpgradeService {
         }
     }
     async detectInstallMethod(os) {
-        if (os === SupportedOs.MACOS && this.#config.homebrew && (await this.#isHomebrewInstalled())) {
+        // Cheap, no-spawn signals are checked first and always win over the cache below, so a fresh
+        // install is picked up immediately rather than waiting on a stale cached method.
+        if (os === SupportedOs.MACOS &&
+            this.#config.homebrew &&
+            this.#isRunningFromHomebrewCellar(this.#config.homebrew.formula)) {
             return InstallMethod.HOMEBREW;
         }
-        if (os === SupportedOs.WINDOWS && this.#config.winget && (await this.#isWingetInstalled())) {
-            return InstallMethod.WINGET;
-        }
         if (os === SupportedOs.LINUX && this.#config.linuxScript && this.#isLinuxScriptInstall()) {
             return InstallMethod.LINUX_SCRIPT;
         }
-        if (this.#config.githubRelease) {
-            return InstallMethod.GITHUB_RELEASE;
+        // Everything else needs an external process spawn (`brew list`, `winget list`) to confirm -
+        // cache the resolved method so that spawn only ever happens once per keystore.
+        const cached = await this.#getCachedInstallMethod();
+        if (cached !== undefined) {
+            return cached;
+        }
+        let detected;
+        if (os === SupportedOs.MACOS && this.#config.homebrew && (await this.#isHomebrewInstalled())) {
+            detected = InstallMethod.HOMEBREW;
+        }
+        else if (os === SupportedOs.WINDOWS &&
+            this.#config.winget &&
+            (await this.#isWingetInstalled())) {
+            detected = InstallMethod.WINGET;
+        }
+        else if (this.#config.githubRelease) {
+            detected = InstallMethod.GITHUB_RELEASE;
+        }
+        if (detected !== undefined) {
+            await this.#cacheInstallMethod(detected);
+        }
+        return detected;
+    }
+    // The opportunistic startup check (see getUpgradeCheckResult()) runs detached from
+    // UpgradeServiceProvider.initService()'s own await chain, so it can still be running after that
+    // scoped KeyValueService access window has closed - a KeyValueService call landing after that
+    // point throws (or could land under a different service's scope entirely). Treat any such
+    // failure as "caching unavailable right now" rather than letting it fail the whole check.
+    async #safeKeyValueCall(op) {
+        try {
+            return await op();
+        }
+        catch (error) {
+            logger.debug(() => `KeyValueService access failed, skipping cache: ${error}`);
+            return undefined;
+        }
+    }
+    async #getCachedInstallMethod() {
+        if (!this.#keyValueService) {
+            return undefined;
+        }
+        const keyValueService = this.#keyValueService;
+        const has = await this.#safeKeyValueCall(() => keyValueService.has(INSTALL_METHOD_CACHE_KEY));
+        if (!has) {
+            return undefined;
+        }
+        const cached = await this.#safeKeyValueCall(() => keyValueService.get(INSTALL_METHOD_CACHE_KEY));
+        if (!cached || Date.now() - cached.checkedAt >= CACHE_TTL_MILLIS) {
+            return undefined;
+        }
+        return cached.method;
+    }
+    async #cacheInstallMethod(method) {
+        if (this.#keyValueService) {
+            const keyValueService = this.#keyValueService;
+            await this.#safeKeyValueCall(() => keyValueService.set(INSTALL_METHOD_CACHE_KEY, { method, checkedAt: Date.now() }));
         }
-        return undefined;
     }
     async checkForUpgrade(osOverride, archOverride, installMethodOverride) {
         const os = osOverride ?? this.detectOs();
@@ -172,7 +262,7 @@ export default class DefaultUpgradeService {
         const hasOverride = osOverride !== undefined || archOverride !== undefined || installMethodOverride !== undefined;
         const checkResult = hasOverride
             ? await this.checkForUpgrade(osOverride, archOverride, installMethodOverride)
-            : await this.getUpgradeCheckResult(true);
+            : await this.getUpgradeCheckResult();
         if (checkResult.status === "unsupported") {
             return {
                 ok: false,
@@ -183,10 +273,6 @@ export default class DefaultUpgradeService {
         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") };
         }
@@ -223,6 +309,21 @@ export default class DefaultUpgradeService {
     #isPlatformSupported(os, arch) {
         return this.#config.supportedPlatforms.some((platform) => platform.os === os && platform.arch === arch);
     }
+    // Homebrew relinks a formula's installed binary from its Cellar directory into a `bin/` symlink,
+    // so resolving the running executable's real path confirms a homebrew install without spawning
+    // `brew`, which has a slow cold start - avoiding it keeps the background upgrade-check
+    // StartupTask (see UpgradeServiceProvider) fast even though it now runs to completion.
+    #isRunningFromHomebrewCellar(formula) {
+        let realExecutable = process.execPath;
+        try {
+            realExecutable = realpathSync(process.execPath);
+        }
+        catch {
+            // process.execPath may not resolve on disk (e.g. a fabricated path in tests) - fall back to
+            // the unresolved path rather than treating that as "not installed".
+        }
+        return realExecutable.includes(`/Cellar/${formula}/`);
+    }
     async #isHomebrewInstalled() {
         if (!this.#spawnService || !this.#config.homebrew) {
             return false;
@@ -241,6 +342,24 @@ export default class DefaultUpgradeService {
         return process.execPath.startsWith("/usr/local/bin/");
     }
     async #getLatestVersion(installMethod) {
+        const cacheKey = `${LATEST_VERSION_CACHE_KEY_PREFIX}${installMethod}`;
+        const keyValueService = this.#keyValueService;
+        if (keyValueService) {
+            const has = await this.#safeKeyValueCall(() => keyValueService.has(cacheKey));
+            if (has) {
+                const cached = await this.#safeKeyValueCall(() => keyValueService.get(cacheKey));
+                if (cached && Date.now() - cached.checkedAt < CACHE_TTL_MILLIS) {
+                    return { ok: true, version: cached.version };
+                }
+            }
+        }
+        const result = await this.#lookupLatestVersion(installMethod);
+        if (result.ok && keyValueService) {
+            await this.#safeKeyValueCall(() => keyValueService.set(cacheKey, { version: result.version, checkedAt: Date.now() }));
+        }
+        return result;
+    }
+    async #lookupLatestVersion(installMethod) {
         switch (installMethod) {
             case InstallMethod.GITHUB_RELEASE:
             case InstallMethod.LINUX_SCRIPT:

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

@@ -1,12 +1,22 @@
 import type { ServiceInfo, ServiceProvider } from "@flowscripter/dynamic-cli-framework-api";
 import type { Context } from "@flowscripter/dynamic-cli-framework-api";
 import type { CLIConfig } from "@flowscripter/dynamic-cli-framework-api";
+import DefaultUpgradeService from "./DefaultUpgradeService.ts";
 import type { UpgradeLocationsConfig } from "./UpgradeLocationsConfig.ts";
+import type { StartupTask } from "@flowscripter/dynamic-cli-framework-api";
+/**
+ * Build the background {@link StartupTask} which opportunistically refreshes the upgrade-check
+ * cache (see {@link DefaultUpgradeService.refreshUpgradeCheckCache}) that the banner task reads
+ * from. Registered separately from {@link UpgradeServiceProvider} itself (which still runs as a
+ * regular blocking init task) so it can run in `"background"` mode.
+ */
+export declare function createUpgradeCheckStartupTask(upgradeService: DefaultUpgradeService, priority: number): StartupTask;
 export default class UpgradeServiceProvider implements ServiceProvider {
     #private;
     readonly serviceId: string;
     readonly servicePriority: number;
     constructor(servicePriority: number, config: UpgradeLocationsConfig);
+    get upgradeService(): DefaultUpgradeService | undefined;
     getServiceInfo(cliConfig: CLIConfig): Promise<ServiceInfo>;
     initService(context: Context): Promise<void>;
 }

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;IAKjC,YAAmB,eAAe,EAAE,MAAM,EAAE,MAAM,EAAE,sBAAsB,EAGzE;IAEM,cAAc,CAAC,SAAS,EAAE,SAAS,GAAG,OAAO,CAAC,WAAW,CAAC,CAOhE;IAEY,WAAW,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAuFxD;CAoCF"}
+{"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;AAYzE,OAAO,qBAAqB,MAAM,4BAA4B,CAAC;AAE/D,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,6BAA6B,CAAC;AAE1E,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,yCAAyC,CAAC;AAI3E;;;;;GAKG;AACH,wBAAgB,6BAA6B,CAC3C,cAAc,EAAE,qBAAqB,EACrC,QAAQ,EAAE,MAAM,GACf,WAAW,CASb;AAED,MAAM,CAAC,OAAO,OAAO,sBAAuB,YAAW,eAAe;;IACpE,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAsB;IAChD,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IAKjC,YAAmB,eAAe,EAAE,MAAM,EAAE,MAAM,EAAE,sBAAsB,EAGzE;IAED,IAAW,cAAc,IAAI,qBAAqB,GAAG,SAAS,CAE7D;IAEM,cAAc,CAAC,SAAS,EAAE,SAAS,GAAG,OAAO,CAAC,WAAW,CAAC,CAOhE;IAEY,WAAW,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAqFxD;CAoCF"}

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

@@ -8,6 +8,22 @@ import DefaultUpgradeService from "./DefaultUpgradeService.js";
 import { UpgradeSubCommand } from "./command/UpgradeSubCommand.js";
 import getLogger from "../../util/logger.js";
 const logger = getLogger("UpgradeServiceProvider");
+/**
+ * Build the background {@link StartupTask} which opportunistically refreshes the upgrade-check
+ * cache (see {@link DefaultUpgradeService.refreshUpgradeCheckCache}) that the banner task reads
+ * from. Registered separately from {@link UpgradeServiceProvider} itself (which still runs as a
+ * regular blocking init task) so it can run in `"background"` mode.
+ */
+export function createUpgradeCheckStartupTask(upgradeService, priority) {
+    return {
+        id: `${UPGRADE_SERVICE_ID}-check`,
+        priority,
+        mode: "background",
+        run: async () => {
+            await upgradeService.refreshUpgradeCheckCache();
+        },
+    };
+}
 export default class UpgradeServiceProvider {
     serviceId = UPGRADE_SERVICE_ID;
     servicePriority;
@@ -18,12 +34,15 @@ export default class UpgradeServiceProvider {
         this.servicePriority = servicePriority;
         this.#config = config;
     }
+    get upgradeService() {
+        return this.#upgradeService;
+    }
     getServiceInfo(cliConfig) {
         this.#cliConfig = cliConfig;
         this.#upgradeService = new DefaultUpgradeService(this.#config, cliConfig);
         return Promise.resolve({
             service: this.#upgradeService,
-            commands: [new UpgradeSubCommand(this.#upgradeService)],
+            commands: [new UpgradeSubCommand()],
         });
     }
     async initService(context) {
@@ -41,18 +60,18 @@ export default class UpgradeServiceProvider {
         if (fetchService === undefined) {
             logger.debug(() => "FetchService not available, upgrade version checks will be unavailable");
         }
-        const printerService = context.getServiceById(PRINTER_SERVICE_ID);
-        upgradeService.setDependencies(spawnService, fetchService, printerService);
-        void upgradeService.getUpgradeCheckResult();
+        const keyValueService = context.doesServiceExist(KEY_VALUE_SERVICE_ID)
+            ? context.getServiceById(KEY_VALUE_SERVICE_ID)
+            : undefined;
+        upgradeService.setContext(context);
         if (!context.doesServiceExist(PROMPTER_SERVICE_ID)) {
             logger.debug(() => "PrompterService not available, skipping auto-upgrade");
             return;
         }
-        if (!context.doesServiceExist(KEY_VALUE_SERVICE_ID)) {
+        if (!keyValueService) {
             logger.debug(() => "KeyValueService not available, skipping auto-upgrade");
             return;
         }
-        const keyValueService = context.getServiceById(KEY_VALUE_SERVICE_ID);
         if (await keyValueService.has("upgrade-status")) {
             const status = await keyValueService.get("upgrade-status");
             if (status === "declined") {

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

@@ -2,15 +2,12 @@ import type { SubCommand } from "@flowscripter/dynamic-cli-framework-api";
 import type { Option } from "@flowscripter/dynamic-cli-framework-api";
 import type { Context } from "@flowscripter/dynamic-cli-framework-api";
 import { type Values } from "@flowscripter/dynamic-cli-framework-api";
-import type DefaultUpgradeService from "../DefaultUpgradeService.ts";
 export declare class UpgradeSubCommand implements SubCommand {
-    #private;
     readonly name = "upgrade";
     readonly description = "Upgrade to the latest available version";
     readonly enableConfiguration = false;
     readonly positionals: never[];
     readonly options: ReadonlyArray<Option>;
-    constructor(upgradeService: DefaultUpgradeService);
     execute(context: Context, argumentValues: Values): Promise<void>;
 }
 //# sourceMappingURL=UpgradeSubCommand.d.ts.map

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;IAIF,YAAmB,cAAc,EAAE,qBAAqB,EAEvD;IAEY,OAAO,CAAC,OAAO,EAAE,OAAO,EAAE,cAAc,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CA4D5E;CACF"}
+{"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;AAYrF,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;IAEW,OAAO,CAAC,OAAO,EAAE,OAAO,EAAE,cAAc,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAuD5E;CACF"}

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

@@ -1,5 +1,5 @@
 import { ValueTypeName } from "@flowscripter/dynamic-cli-framework-api";
-import { Icon, InstallMethod, PRINTER_SERVICE_ID, SupportedArch, SupportedOs, } from "@flowscripter/dynamic-cli-framework-api";
+import { Icon, InstallMethod, PRINTER_SERVICE_ID, SupportedArch, SupportedOs, UPGRADE_SERVICE_ID, } from "@flowscripter/dynamic-cli-framework-api";
 export class UpgradeSubCommand {
     name = "upgrade";
     description = "Upgrade to the latest available version";
@@ -21,12 +21,9 @@ export class UpgradeSubCommand {
             description: "Override the detected install method",
         },
     ];
-    #upgradeService;
-    constructor(upgradeService) {
-        this.#upgradeService = upgradeService;
-    }
     async execute(context, argumentValues) {
         const printerService = context.getServiceById(PRINTER_SERVICE_ID);
+        const upgradeService = context.getServiceById(UPGRADE_SERVICE_ID);
         const cliName = context.cliConfig.name;
         const currentVersion = context.cliConfig.version;
         const os = argumentValues.os;
@@ -34,8 +31,8 @@ export class UpgradeSubCommand {
         const installMethod = argumentValues["install-method"];
         await printerService.showSpinner(`Looking for version newer than ${currentVersion}`);
         const checkResult = os === undefined && installMethod === undefined
-            ? await this.#upgradeService.getUpgradeCheckResult(true)
-            : await this.#upgradeService.checkForUpgrade(os, arch, installMethod);
+            ? await upgradeService.refreshUpgradeCheckCache()
+            : await upgradeService.checkForUpgrade(os, arch, installMethod);
         await printerService.hideSpinner();
         if (checkResult.status === "unsupported") {
             await printerService.error(`No upgrade location is configured for the detected or requested platform.\n`, Icon.FAILURE);
@@ -45,16 +42,11 @@ export class UpgradeSubCommand {
             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`, Icon.INFORMATION);
             return;
         }
-        const upgradeResult = await this.#upgradeService.upgrade(os, arch, installMethod);
+        const upgradeResult = await upgradeService.upgrade(os, arch, installMethod);
         if (!upgradeResult.ok) {
             await printerService.error(`Failed to upgrade ${cliName}: ${upgradeResult.error?.message ?? "unknown error"}\n`, Icon.FAILURE);
             return;

package/dist/src/startup/banner/bannerStartupTask.d.ts

@@ -0,0 +1,17 @@
+import type { StartupTask } from "@flowscripter/dynamic-cli-framework-api";
+export declare const BANNER_STARTUP_TASK_ID = "@flowscripter/dynamic-cli-framework/banner-startup-task";
+/**
+ * Build the ascii banner {@link StartupTask}, replacing the old `BannerServiceProvider`.
+ *
+ * A consumer opts in by passing the result of this function in the `serviceProviders` array
+ * argument of {@link launchMultiCommandCLI}/{@link launchSingleCommandCLI} (or via
+ * `BaseCLI.addStartupTask`), the same way `new BannerServiceProvider(priority)` used to be passed
+ * in that array - there's no default/automatic banner registration.
+ *
+ * @param priority the priority of the task (higher runs earlier - the same semantics
+ * `BannerServiceProvider.servicePriority` had).
+ * @param fontName an optional [FIGlet](http://www.figlet.org) font name to use for the banner,
+ * defaults to "standard".
+ */
+export default function createBannerStartupTask(priority: number, fontName?: string): StartupTask;
+//# sourceMappingURL=bannerStartupTask.d.ts.map

package/dist/src/startup/banner/bannerStartupTask.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bannerStartupTask.d.ts","sourceRoot":"","sources":["../../../../src/startup/banner/bannerStartupTask.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAIV,WAAW,EAEZ,MAAM,yCAAyC,CAAC;AAYjD,eAAO,MAAM,sBAAsB,4DAA4D,CAAC;AAEhG;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,OAAO,UAAU,uBAAuB,CAC7C,QAAQ,EAAE,MAAM,EAChB,QAAQ,SAAa,GACpB,WAAW,CA2Db"}

package/dist/src/startup/banner/bannerStartupTask.js

@@ -0,0 +1,66 @@
+import { ASCII_BANNER_GENERATOR_SERVICE_ID, CONFIGURATION_SERVICE_ID, KEY_VALUE_SERVICE_ID, PRINTER_SERVICE_ID, } from "@flowscripter/dynamic-cli-framework-api";
+import { UPGRADE_CHECK_CACHE_KEY } from "../../service/upgrade/DefaultUpgradeService.js";
+import NoBannerCommand, {} from "./command/NoBannerCommand.js";
+export const BANNER_STARTUP_TASK_ID = "@flowscripter/dynamic-cli-framework/banner-startup-task";
+/**
+ * Build the ascii banner {@link StartupTask}, replacing the old `BannerServiceProvider`.
+ *
+ * A consumer opts in by passing the result of this function in the `serviceProviders` array
+ * argument of {@link launchMultiCommandCLI}/{@link launchSingleCommandCLI} (or via
+ * `BaseCLI.addStartupTask`), the same way `new BannerServiceProvider(priority)` used to be passed
+ * in that array - there's no default/automatic banner registration.
+ *
+ * @param priority the priority of the task (higher runs earlier - the same semantics
+ * `BannerServiceProvider.servicePriority` had).
+ * @param fontName an optional [FIGlet](http://www.figlet.org) font name to use for the banner,
+ * defaults to "standard".
+ */
+export default function createBannerStartupTask(priority, fontName = "standard") {
+    const state = { printBanner: true };
+    return {
+        id: BANNER_STARTUP_TASK_ID,
+        priority,
+        mode: "blocking",
+        modifierCommands: [new NoBannerCommand(state, priority)],
+        run: async (context) => {
+            if (!state.printBanner) {
+                return;
+            }
+            const printerService = context.getServiceById(PRINTER_SERVICE_ID);
+            const asciiBannerGeneratorService = context.getServiceById(ASCII_BANNER_GENERATOR_SERVICE_ID);
+            const { cliConfig } = context;
+            const bannerText = await asciiBannerGeneratorService.generate(cliConfig.name.toUpperCase(), {
+                fontName,
+                subMessage: cliConfig.subMessage,
+            });
+            await printerService.info(printerService.blue(bannerText));
+            if (cliConfig.description !== undefined) {
+                await printerService.info(`  ${printerService.primary(cliConfig.description)}\n`);
+            }
+            if (cliConfig.version.length > 0) {
+                let versionLine = "version: " + cliConfig.version;
+                // Cheap cache read only - never calls checkForUpgrade()/getUpgradeCheckResult() live,
+                // since that could stall startup on a network/spawn call. A first-ever run (no cached
+                // key yet) simply shows no upgrade-available suffix - that's expected, not a bug.
+                if (context.doesServiceExist(KEY_VALUE_SERVICE_ID)) {
+                    const keyValueService = context.getServiceById(KEY_VALUE_SERVICE_ID);
+                    if (await keyValueService.has(UPGRADE_CHECK_CACHE_KEY)) {
+                        const result = (await keyValueService.get(UPGRADE_CHECK_CACHE_KEY));
+                        if (result.status === "checked" && result.updateAvailable) {
+                            versionLine += ` (${result.latestVersion} available, run '${cliConfig.name} upgrade')`;
+                        }
+                    }
+                }
+                await printerService.info(`  ${printerService.secondary(versionLine)}\n`);
+            }
+            if (context.doesServiceExist(CONFIGURATION_SERVICE_ID)) {
+                const configurationService = context.getServiceById(CONFIGURATION_SERVICE_ID);
+                const configLocation = configurationService.configLocation;
+                if (configLocation && configLocation.length > 0) {
+                    await printerService.info(`  ${printerService.secondary("config: " + configLocation)}\n`);
+                }
+            }
+            await printerService.info("\n");
+        },
+    };
+}

package/dist/src/{service → startup}/banner/command/NoBannerCommand.d.ts

@@ -2,7 +2,13 @@ import type { GlobalModifierCommand } from "@flowscripter/dynamic-cli-framework-
 import { type SingleValueType } from "@flowscripter/dynamic-cli-framework-api";
 import type { Context } from "@flowscripter/dynamic-cli-framework-api";
 import type { GlobalCommandArgument } from "@flowscripter/dynamic-cli-framework-api";
-import type BannerServiceProvider from "../BannerServiceProvider.ts";
+/**
+ * Task-local, mutable state shared between {@link NoBannerCommand} and the banner
+ * {@link StartupTask}'s `run()`, in place of a held `BannerServiceProvider` reference.
+ */
+export interface BannerState {
+    printBanner: boolean;
+}
 /**
  * Command to disable banner output for the CLI application.
  */
@@ -13,7 +19,7 @@ export default class NoBannerCommand implements GlobalModifierCommand {
     readonly enableConfiguration = true;
     readonly argument: GlobalCommandArgument;
     readonly executePriority: number;
-    constructor(bannerServiceProvider: BannerServiceProvider, executePriority: number);
+    constructor(state: BannerState, executePriority: number);
     execute(_context: Context, argumentValue: SingleValueType): Promise<void>;
 }
 //# sourceMappingURL=NoBannerCommand.d.ts.map

package/dist/src/startup/banner/command/NoBannerCommand.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"NoBannerCommand.d.ts","sourceRoot":"","sources":["../../../../../src/startup/banner/command/NoBannerCommand.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,yCAAyC,CAAC;AACrF,OAAO,EAAE,KAAK,eAAe,EAAiB,MAAM,yCAAyC,CAAC;AAC9F,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,yCAAyC,CAAC;AACvE,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,yCAAyC,CAAC;AAErF;;;GAGG;AACH,MAAM,WAAW,WAAW;IAC1B,WAAW,EAAE,OAAO,CAAC;CACtB;AAED;;GAEG;AACH,MAAM,CAAC,OAAO,OAAO,eAAgB,YAAW,qBAAqB;;IACnE,QAAQ,CAAC,IAAI,eAAe;IAC5B,QAAQ,CAAC,WAAW,8BAA8B;IAClD,QAAQ,CAAC,mBAAmB,QAAQ;IACpC,QAAQ,CAAC,QAAQ,EAAE,qBAAqB,CAItC;IACF,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IAIjC,YAAmB,KAAK,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,EAG7D;IAEM,OAAO,CAAC,QAAQ,EAAE,OAAO,EAAE,aAAa,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC,CAI/E;CACF"}

package/dist/src/{service → startup}/banner/command/NoBannerCommand.js

@@ -12,13 +12,13 @@ export default class NoBannerCommand {
         configurationKey: "NO_BANNER",
     };
     executePriority;
-    #bannerServiceProvider;
-    constructor(bannerServiceProvider, executePriority) {
-        this.#bannerServiceProvider = bannerServiceProvider;
+    #state;
+    constructor(state, executePriority) {
+        this.#state = state;
         this.executePriority = executePriority;
     }
     execute(_context, argumentValue) {
-        this.#bannerServiceProvider.printBanner = !argumentValue;
+        this.#state.printBanner = !argumentValue;
         return Promise.resolve();
     }
 }

package/index.ts

@@ -52,8 +52,10 @@ export type {
   ChiselBannerGenerateOptions,
 } from "./src/service/chiselAsciiBannerGenerator/ChiselFontAsciiBannerGeneratorService.ts";
 
-export { default as BannerServiceProvider } from "./src/service/banner/BannerServiceProvider.ts";
+export { default as createBannerStartupTask } from "./src/startup/banner/bannerStartupTask.ts";
 
+export { CONFIGURATION_SERVICE_ID } from "@flowscripter/dynamic-cli-framework-api";
+export type { ConfigurationService } from "@flowscripter/dynamic-cli-framework-api";
 export { KEY_VALUE_SERVICE_ID } from "@flowscripter/dynamic-cli-framework-api";
 export { SECRET_SENTINEL_PREFIX } from "@flowscripter/dynamic-cli-framework-api";
 export type { KeyValueService } from "@flowscripter/dynamic-cli-framework-api";
@@ -62,7 +64,11 @@ export { default as DefaultKeyValueService } from "./src/service/configuration/D
 export { default as DefaultSecretService } from "./src/service/configuration/DefaultSecretService.ts";
 export type { SecretsApi } from "./src/service/configuration/DefaultSecretService.ts";
 export { default as ConfigCommand } from "./src/service/configuration/command/ConfigCommand.ts";
-export { default as ConfigurationServiceProvider } from "./src/service/configuration/ConfigurationServiceProvider.ts";
+export {
+  default as ConfigurationServiceProvider,
+  type KeyValueServiceScopeType,
+} from "./src/service/configuration/ConfigurationServiceProvider.ts";
+export { default as KeyValueServiceProvider } from "./src/service/configuration/KeyValueServiceProvider.ts";
 
 export { PRINTER_SERVICE_ID } from "@flowscripter/dynamic-cli-framework-api";
 export type { PrinterService } from "@flowscripter/dynamic-cli-framework-api";
@@ -71,10 +77,20 @@ export { default as DefaultPrinterService } from "./src/service/printer/DefaultP
 export { default as PrinterServiceProvider } from "./src/service/printer/PrinterServiceProvider.ts";
 
 export { SHUTDOWN_SERVICE_ID } from "@flowscripter/dynamic-cli-framework-api";
-export type { ShutdownService } from "@flowscripter/dynamic-cli-framework-api";
+export type { ShutdownService, ShutdownTask } from "@flowscripter/dynamic-cli-framework-api";
 export { default as DefaultShutdownService } from "./src/service/shutdown/DefaultShutdownService.ts";
 export { default as ShutdownServiceProvider } from "./src/service/shutdown/ShutdownServiceProvider.ts";
 
+export { STARTUP_SERVICE_ID } from "@flowscripter/dynamic-cli-framework-api";
+export type {
+  StartupService,
+  StartupTask,
+  StartupTaskContext,
+  StartupTaskMode,
+} from "@flowscripter/dynamic-cli-framework-api";
+export { default as DefaultStartupService } from "./src/service/startup/DefaultStartupService.ts";
+export { default as StartupServiceProvider } from "./src/service/startup/StartupServiceProvider.ts";
+
 export { FETCH_SERVICE_ID } from "@flowscripter/dynamic-cli-framework-api";
 export type { FetchOptions, FetchService } from "@flowscripter/dynamic-cli-framework-api";
 export { default as DefaultFetchService } from "./src/service/fetch/DefaultFetchService.ts";