@flowscripter/dynamic-cli-framework 9.0.3 → 9.1.0

package/dist/src/service/upgrade/method/githubRelease.js

@@ -0,0 +1,132 @@
+import process from "node:process";
+import { mkdtemp, rename, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { SupportedArch, SupportedOs, } from "@flowscripter/dynamic-cli-framework-api";
+import { spawnQuoted } from "./shared.js";
+const OS_LABELS = {
+    [SupportedOs.LINUX]: "Linux",
+    [SupportedOs.MACOS]: "MacOS",
+    [SupportedOs.WINDOWS]: "Windows",
+};
+export async function getLatestGithubReleaseVersion(fetchService, location) {
+    if (!location) {
+        return { ok: false, error: new Error("No githubRelease location configured") };
+    }
+    if (!fetchService) {
+        return { ok: false, error: new Error("FetchService is not available") };
+    }
+    const { owner, repo } = location;
+    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 fetchService.fetch(`https://github.com/${owner}/${repo}/releases/latest`, { redirect: "manual" });
+        const redirect = response.headers.get("location");
+        const version = redirect ? /\/releases\/tag\/v?([^/]+)$/.exec(redirect)?.[1] : undefined;
+        if (!version) {
+            return {
+                ok: false,
+                error: new Error(`Unexpected response resolving latest release for ${owner}/${repo}: HTTP ${response.status}`),
+            };
+        }
+        return { ok: true, version };
+    }
+    catch (error) {
+        return {
+            ok: false,
+            error: new Error(`Failed to fetch latest GitHub release for ${owner}/${repo}: ${error}`),
+        };
+    }
+}
+export async function upgradeViaGithubRelease(spawnService, fetchService, printerService, location, cliName, os, arch) {
+    const { owner, repo, assetPattern } = location;
+    // macOS release assets use "aarch64" rather than "arm64" for the arm64 build; x64 (including
+    // Intel Macs) always uses "x64" regardless of os.
+    const archLabel = arch === SupportedArch.X64 ? "x64" : os === SupportedOs.MACOS ? "aarch64" : "arm64";
+    const assetName = assetPattern.replace("{os}", OS_LABELS[os]).replace("{arch}", archLabel);
+    const url = `https://github.com/${owner}/${repo}/releases/latest/download/${assetName}`;
+    // longRunning: true gets cooperative Ctrl-C handling during what can be the slowest step of
+    // the upgrade.
+    const response = await fetchService.fetch(url, { longRunning: true });
+    if (!response.ok) {
+        throw new Error(`Failed to download release asset '${assetName}': HTTP ${response.status}`);
+    }
+    const archiveData = await response.arrayBuffer();
+    const tmpDir = await mkdtemp(join(tmpdir(), "upgrade-"));
+    const archivePath = join(tmpDir, assetName);
+    await Bun.write(archivePath, archiveData);
+    const currentExecutable = process.execPath;
+    if (os === SupportedOs.WINDOWS) {
+        const extractResult = await spawnQuoted(spawnService, printerService, [
+            "powershell",
+            "-Command",
+            `Expand-Archive -Path '${archivePath}' -DestinationPath '${tmpDir}' -Force`,
+        ]);
+        if (!extractResult.ok) {
+            throw new Error("Failed to extract release archive");
+        }
+        const extractedBinary = join(tmpDir, `${cliName}.exe`);
+        const oldPath = `${currentExecutable}.old.exe`;
+        // Best-effort cleanup of a stale "<exe>.old.exe" left behind by a *previous* upgrade run.
+        // Windows won't let us delete the just-renamed-aside exe while this process still has it
+        // open/mapped - that can only happen once we're no longer holding it, i.e. at the start of
+        // the NEXT invocation, before we move today's running exe aside. Ignore failures: the file
+        // may not exist, or may still be locked (e.g. another instance still running). Not quoted -
+        // this is expected to fail silently, there's nothing worth showing the user.
+        await spawnService.spawn(["cmd", "/c", "del", "/f", "/q", oldPath], {
+            mode: "ignore",
+        });
+        const moveResult = await spawnQuoted(spawnService, printerService, [
+            "cmd",
+            "/c",
+            "move",
+            "/y",
+            currentExecutable,
+            oldPath,
+        ]);
+        if (!moveResult.ok) {
+            throw new Error("Failed to move current executable aside");
+        }
+        const copyResult = await spawnQuoted(spawnService, printerService, [
+            "cmd",
+            "/c",
+            "copy",
+            "/y",
+            extractedBinary,
+            currentExecutable,
+        ]);
+        if (!copyResult.ok) {
+            throw new Error("Failed to copy new executable into place");
+        }
+    }
+    else {
+        const extractResult = await spawnQuoted(spawnService, printerService, [
+            "unzip",
+            "-o",
+            archivePath,
+            "-d",
+            tmpDir,
+        ]);
+        if (!extractResult.ok) {
+            throw new Error("Failed to extract release archive");
+        }
+        const extractedBinary = join(tmpDir, cliName);
+        // Extract into a staging file in the SAME directory as the running executable (not
+        // os.tmpdir(), which may be a different filesystem/mount), then atomically rename it over
+        // currentExecutable. This avoids ETXTBSY: the kernel refuses to open-for-write the inode
+        // mapped as a running process's text segment, but rename() only swaps the directory entry
+        // to point at a different inode - the running process keeps executing from its original,
+        // now-unlinked-but-still-open inode until it next execs/restarts.
+        const stagingDir = await mkdtemp(join(dirname(currentExecutable), ".upgrade-"));
+        try {
+            const stagingBinary = join(stagingDir, cliName);
+            await Bun.write(stagingBinary, Bun.file(extractedBinary));
+            await spawnService.spawn(["chmod", "+x", stagingBinary], { mode: "ignore" });
+            await rename(stagingBinary, currentExecutable);
+        }
+        finally {
+            await rm(stagingDir, { recursive: true, force: true });
+        }
+    }
+}

package/dist/src/service/upgrade/method/homebrew.d.ts

@@ -0,0 +1,11 @@
+import type { FetchService, PrinterService, SpawnService } from "@flowscripter/dynamic-cli-framework-api";
+import { type SemVer } from "semver";
+import type { HomebrewLocation } from "../UpgradeLocationsConfig.ts";
+import { type VersionLookupResult } from "./shared.ts";
+export declare function parseBrewInstalledVersions(output: string, formula: string): SemVer[];
+export declare function isRunningFromHomebrewCellar(formula: string): boolean;
+export declare function resolveHomebrewOptExecutable(location: HomebrewLocation | undefined): string | undefined;
+export declare function isHomebrewInstalled(spawnService: SpawnService | undefined, location: HomebrewLocation | undefined): Promise<boolean>;
+export declare function getLatestHomebrewVersion(fetchService: FetchService | undefined, location: HomebrewLocation | undefined): Promise<VersionLookupResult>;
+export declare function upgradeViaHomebrew(spawnService: SpawnService, printerService: PrinterService | undefined, location: HomebrewLocation, expectedVersion: string): Promise<void>;
+//# sourceMappingURL=homebrew.d.ts.map

package/dist/src/service/upgrade/method/homebrew.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"homebrew.d.ts","sourceRoot":"","sources":["../../../../../src/service/upgrade/method/homebrew.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EACV,YAAY,EACZ,cAAc,EACd,YAAY,EACb,MAAM,yCAAyC,CAAC;AACjD,OAAe,EAAE,KAAK,MAAM,EAAE,MAAM,QAAQ,CAAC;AAC7C,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,8BAA8B,CAAC;AACrE,OAAO,EAAqC,KAAK,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAI1F,wBAAgB,0BAA0B,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,EAAE,CAapF;AAgBD,wBAAgB,2BAA2B,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAEpE;AAKD,wBAAgB,4BAA4B,CAC1C,QAAQ,EAAE,gBAAgB,GAAG,SAAS,GACrC,MAAM,GAAG,SAAS,CAapB;AAED,wBAAsB,mBAAmB,CACvC,YAAY,EAAE,YAAY,GAAG,SAAS,EACtC,QAAQ,EAAE,gBAAgB,GAAG,SAAS,GACrC,OAAO,CAAC,OAAO,CAAC,CASlB;AAED,wBAAsB,wBAAwB,CAC5C,YAAY,EAAE,YAAY,GAAG,SAAS,EACtC,QAAQ,EAAE,gBAAgB,GAAG,SAAS,GACrC,OAAO,CAAC,mBAAmB,CAAC,CAuC9B;AAKD,wBAAsB,kBAAkB,CACtC,YAAY,EAAE,YAAY,EAC1B,cAAc,EAAE,cAAc,GAAG,SAAS,EAC1C,QAAQ,EAAE,gBAAgB,EAC1B,eAAe,EAAE,MAAM,GACtB,OAAO,CAAC,IAAI,CAAC,CA+Bf"}

package/dist/src/service/upgrade/method/homebrew.js

@@ -0,0 +1,132 @@
+import process from "node:process";
+import { existsSync, realpathSync } from "node:fs";
+import { basename, join } from "node:path";
+import semver, {} from "semver";
+import { describeSpawnFailure, spawnQuoted } from "./shared.js";
+// `brew list --versions <formula>` prints the formula name followed by one or more installed
+// versions, each optionally prefixed with "v" and optionally suffixed with a "_N" revision.
+export function parseBrewInstalledVersions(output, formula) {
+    const tokens = output.trim().split(/\s+/).filter(Boolean);
+    if (tokens[0] === formula) {
+        tokens.shift();
+    }
+    const versions = [];
+    for (const token of tokens) {
+        const version = semver.coerce(token.replace(/^v/i, "").replace(/_\d+$/, ""));
+        if (version) {
+            versions.push(version);
+        }
+    }
+    return versions;
+}
+function resolveRealExecutable() {
+    try {
+        return 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 process.execPath;
+    }
+}
+// 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 runs to completion.
+export function isRunningFromHomebrewCellar(formula) {
+    return resolveRealExecutable().includes(`/Cellar/${formula}/`);
+}
+// The running executable lives in a version-specific Cellar directory, e.g.
+// "<prefix>/Cellar/<formula>/<version>/bin/<exe>", while "<prefix>/opt/<formula>" links to the
+// installed version, so the upgraded executable is "<prefix>/opt/<formula>/bin/<exe>".
+export function resolveHomebrewOptExecutable(location) {
+    if (!location) {
+        return undefined;
+    }
+    const { formula } = location;
+    const realExecutable = resolveRealExecutable();
+    const cellarIndex = realExecutable.indexOf(`/Cellar/${formula}/`);
+    if (cellarIndex === -1) {
+        return undefined;
+    }
+    const prefix = realExecutable.slice(0, cellarIndex);
+    const executable = join(prefix, "opt", formula, "bin", basename(realExecutable));
+    return existsSync(executable) ? executable : undefined;
+}
+export async function isHomebrewInstalled(spawnService, location) {
+    if (!spawnService || !location) {
+        return false;
+    }
+    const result = await spawnService.spawn(["brew", "list", "--versions", location.formula], {
+        mode: "ignore",
+        longRunning: false,
+    });
+    return result.ok;
+}
+export async function getLatestHomebrewVersion(fetchService, location) {
+    if (!location) {
+        return { ok: false, error: new Error("No homebrew location configured") };
+    }
+    if (!fetchService) {
+        return { ok: false, error: new Error("FetchService is not available") };
+    }
+    const { tap, formula } = location;
+    const [tapOwner, tapName] = tap.split("/");
+    if (!tapOwner || !tapName) {
+        return { ok: false, error: new Error(`Invalid homebrew tap '${tap}'`) };
+    }
+    try {
+        const response = await fetchService.fetch(`https://raw.githubusercontent.com/${tapOwner}/homebrew-${tapName}/main/${formula}.rb`);
+        if (!response.ok) {
+            return {
+                ok: false,
+                error: new Error(`Failed to fetch homebrew formula for ${tap}/${formula}: HTTP ${response.status}`),
+            };
+        }
+        const text = await response.text();
+        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) {
+        return {
+            ok: false,
+            error: new Error(`Failed to fetch homebrew formula for ${tap}/${formula}: ${error}`),
+        };
+    }
+}
+// The latest version is read from the tap's formula on GitHub, but `brew upgrade` only sees the
+// local tap clone, which is stale until `brew update` runs. A stale tap makes `brew upgrade`
+// exit 0 with "already installed", so update first and then confirm the installed version.
+export async function upgradeViaHomebrew(spawnService, printerService, location, expectedVersion) {
+    const { tap, formula } = location;
+    const updateResult = await spawnQuoted(spawnService, printerService, ["brew", "update"]);
+    if (!updateResult.ok) {
+        throw new Error(`brew update failed: ${describeSpawnFailure(updateResult)}`);
+    }
+    const result = await spawnQuoted(spawnService, printerService, [
+        "brew",
+        "upgrade",
+        `${tap}/${formula}`,
+    ]);
+    if (!result.ok) {
+        throw new Error(`brew upgrade failed: ${describeSpawnFailure(result)}`);
+    }
+    const lines = [];
+    const listResult = await spawnService.spawn(["brew", "list", "--versions", formula], {
+        mode: "wrapped",
+        longRunning: false,
+        onOutput: (line) => lines.push(line),
+    });
+    const installed = lines.join(" ").trim();
+    const expected = semver.coerce(expectedVersion);
+    const isExpectedInstalled = parseBrewInstalledVersions(installed, formula).some((version) => expected !== null && semver.eq(version, expected));
+    if (!listResult.ok || !isExpectedInstalled) {
+        throw new Error(`brew upgrade completed but version ${expectedVersion} is not installed (installed: ${installed || "unknown"})`);
+    }
+}

package/dist/src/service/upgrade/method/linuxScript.d.ts

@@ -0,0 +1,5 @@
+import type { PrinterService, SpawnService } from "@flowscripter/dynamic-cli-framework-api";
+import type { LinuxScriptLocation } from "../UpgradeLocationsConfig.ts";
+export declare function isLinuxScriptInstall(): boolean;
+export declare function upgradeViaLinuxScript(spawnService: SpawnService, printerService: PrinterService | undefined, location: LinuxScriptLocation): Promise<void>;
+//# sourceMappingURL=linuxScript.d.ts.map

package/dist/src/service/upgrade/method/linuxScript.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"linuxScript.d.ts","sourceRoot":"","sources":["../../../../../src/service/upgrade/method/linuxScript.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,yCAAyC,CAAC;AAC5F,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,8BAA8B,CAAC;AAGxE,wBAAgB,oBAAoB,IAAI,OAAO,CAE9C;AAED,wBAAsB,qBAAqB,CACzC,YAAY,EAAE,YAAY,EAC1B,cAAc,EAAE,cAAc,GAAG,SAAS,EAC1C,QAAQ,EAAE,mBAAmB,GAC5B,OAAO,CAAC,IAAI,CAAC,CASf"}

package/dist/src/service/upgrade/method/linuxScript.js

@@ -0,0 +1,15 @@
+import process from "node:process";
+import { describeSpawnFailure, spawnQuoted } from "./shared.js";
+export function isLinuxScriptInstall() {
+    return process.execPath.startsWith("/usr/local/bin/");
+}
+export async function upgradeViaLinuxScript(spawnService, printerService, location) {
+    const result = await spawnQuoted(spawnService, printerService, [
+        "sh",
+        "-c",
+        `curl -fsSL ${location.scriptUrl} | sh`,
+    ]);
+    if (!result.ok) {
+        throw new Error(`Install script failed: ${describeSpawnFailure(result)}`);
+    }
+}

package/dist/src/service/upgrade/method/shared.d.ts

@@ -0,0 +1,13 @@
+import type { PrinterService, SpawnResult, SpawnService } from "@flowscripter/dynamic-cli-framework-api";
+export type VersionLookupResult = {
+    readonly ok: true;
+    readonly version: string;
+} | {
+    readonly ok: false;
+    readonly error: Error;
+};
+export declare function describeSpawnFailure(result: Extract<SpawnResult, {
+    ok: false;
+}>): string;
+export declare function spawnQuoted(spawnService: SpawnService, printerService: PrinterService | undefined, command: ReadonlyArray<string>): Promise<SpawnResult>;
+//# sourceMappingURL=shared.d.ts.map

package/dist/src/service/upgrade/method/shared.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shared.d.ts","sourceRoot":"","sources":["../../../../../src/service/upgrade/method/shared.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,cAAc,EACd,WAAW,EACX,YAAY,EACb,MAAM,yCAAyC,CAAC;AAEjD,MAAM,MAAM,mBAAmB,GAC3B;IAAE,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GAC/C;IAAE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAA;CAAE,CAAC;AAElD,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,OAAO,CAAC,WAAW,EAAE;IAAE,EAAE,EAAE,KAAK,CAAA;CAAE,CAAC,GAAG,MAAM,CAIxF;AAKD,wBAAsB,WAAW,CAC/B,YAAY,EAAE,YAAY,EAC1B,cAAc,EAAE,cAAc,GAAG,SAAS,EAC1C,OAAO,EAAE,aAAa,CAAC,MAAM,CAAC,GAC7B,OAAO,CAAC,WAAW,CAAC,CA2BtB"}

package/dist/src/service/upgrade/method/shared.js

@@ -0,0 +1,33 @@
+export function describeSpawnFailure(result) {
+    return "timedOut" in result
+        ? "timed out"
+        : (result.error?.message ?? `exit code ${result.exitCode}`);
+}
+// 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)
+// but left on screen on failure (so the diagnostic output remains visible).
+export async function spawnQuoted(spawnService, printerService, command) {
+    if (!printerService) {
+        return spawnService.spawn(command, { mode: "ignore" });
+    }
+    printerService.startQuote();
+    printerService.startMark();
+    // onOutput is synchronous and may be called concurrently for stdout/stderr lines, but
+    // printerService.info() is async and must not be invoked concurrently with itself - queue
+    // writes so they're applied one at a time, in call order.
+    let writeQueue = Promise.resolve();
+    const onOutput = (line) => {
+        writeQueue = writeQueue.then(() => printerService.info(`${line}\n`));
+    };
+    const result = await spawnService.spawn(command, { mode: "wrapped", onOutput });
+    await writeQueue;
+    printerService.endQuote();
+    printerService.endMark();
+    if (result.ok) {
+        await printerService.clearMarked();
+    }
+    else {
+        printerService.discardMark();
+    }
+    return result;
+}

package/dist/src/service/upgrade/method/winget.d.ts

@@ -0,0 +1,7 @@
+import type { PrinterService, SpawnService } from "@flowscripter/dynamic-cli-framework-api";
+import type { WingetLocation } from "../UpgradeLocationsConfig.ts";
+import { type VersionLookupResult } from "./shared.ts";
+export declare function isWingetInstalled(spawnService: SpawnService | undefined, location: WingetLocation | undefined): Promise<boolean>;
+export declare function getLatestWingetVersion(spawnService: SpawnService | undefined, location: WingetLocation | undefined): Promise<VersionLookupResult>;
+export declare function upgradeViaWinget(spawnService: SpawnService, printerService: PrinterService | undefined, location: WingetLocation): Promise<void>;
+//# sourceMappingURL=winget.d.ts.map

package/dist/src/service/upgrade/method/winget.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"winget.d.ts","sourceRoot":"","sources":["../../../../../src/service/upgrade/method/winget.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,yCAAyC,CAAC;AAC5F,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAC;AACnE,OAAO,EAAqC,KAAK,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAE1F,wBAAsB,iBAAiB,CACrC,YAAY,EAAE,YAAY,GAAG,SAAS,EACtC,QAAQ,EAAE,cAAc,GAAG,SAAS,GACnC,OAAO,CAAC,OAAO,CAAC,CASlB;AAED,wBAAsB,sBAAsB,CAC1C,YAAY,EAAE,YAAY,GAAG,SAAS,EACtC,QAAQ,EAAE,cAAc,GAAG,SAAS,GACnC,OAAO,CAAC,mBAAmB,CAAC,CAuB9B;AAED,wBAAsB,gBAAgB,CACpC,YAAY,EAAE,YAAY,EAC1B,cAAc,EAAE,cAAc,GAAG,SAAS,EAC1C,QAAQ,EAAE,cAAc,GACvB,OAAO,CAAC,IAAI,CAAC,CAaf"}

package/dist/src/service/upgrade/method/winget.js

@@ -0,0 +1,49 @@
+import { describeSpawnFailure, spawnQuoted } from "./shared.js";
+export async function isWingetInstalled(spawnService, location) {
+    if (!spawnService || !location) {
+        return false;
+    }
+    const result = await spawnService.spawn(["winget", "list", "--id", location.packageId], {
+        mode: "ignore",
+        longRunning: false,
+    });
+    return result.ok;
+}
+export async function getLatestWingetVersion(spawnService, location) {
+    if (!location) {
+        return { ok: false, error: new Error("No winget location configured") };
+    }
+    if (!spawnService) {
+        return { ok: false, error: new Error("SpawnService is not available") };
+    }
+    const lines = [];
+    const result = await spawnService.spawn(["winget", "show", "--id", location.packageId], {
+        mode: "wrapped",
+        longRunning: false,
+        onOutput: (line) => lines.push(line),
+    });
+    if (!result.ok) {
+        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 { ok: true, version: match[1] };
+        }
+    }
+    return { ok: false, error: new Error("Could not parse version from winget output") };
+}
+export async function upgradeViaWinget(spawnService, printerService, location) {
+    const result = await spawnQuoted(spawnService, printerService, [
+        "winget",
+        "upgrade",
+        "--id",
+        location.packageId,
+        "--silent",
+        "--accept-package-agreements",
+        "--accept-source-agreements",
+    ]);
+    if (!result.ok) {
+        throw new Error(`winget upgrade failed: ${describeSpawnFailure(result)}`);
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flowscripter/dynamic-cli-framework",
-  "version": "9.0.3",
+  "version": "9.1.0",
   "description": "A framework for developing CLI applications which supports dynamic discovery and installation of new commands",
   "keywords": [
     "bun",

package/src/cli/BaseCLI.ts

@@ -36,6 +36,7 @@ import KeyValueServiceProvider from "../service/configuration/KeyValueServicePro
 import PrinterServiceProvider from "../service/printer/PrinterServiceProvider.ts";
 import TableGeneratorServiceProvider from "../service/tableGenerator/TableGeneratorServiceProvider.ts";
 import { run } from "../runtime/runner.ts";
+import { awaitBackgroundTasks } from "../runtime/lifecycle/BackgroundTasks.ts";
 import { printRuntimeError } from "../util/runnerHelper.ts";
 
 import { WritableStream } from "node:stream/web";
@@ -510,6 +511,7 @@ export default class BaseCLI implements CLI {
         error: error as Error,
       };
     } finally {
+      await awaitBackgroundTasks();
       await ShutdownServiceProvider.shutdown();
     }
   }

package/src/runtime/lifecycle/BackgroundTasks.ts

@@ -0,0 +1,96 @@
+import getLogger from "../../util/logger.ts";
+
+const logger = getLogger("BackgroundTasks");
+
+/**
+ * How long, at shutdown, to wait for in-flight "background" startup tasks before abandoning them.
+ */
+export const BACKGROUND_TASK_GRACE_PERIOD_MS = 1000;
+
+interface InFlightTask {
+  readonly id: string;
+  readonly startedAt: number;
+  settled: Promise<void>;
+}
+
+const inFlightTasks = new Set<InFlightTask>();
+
+function elapsedMs(task: InFlightTask): number {
+  return Math.round(performance.now() - task.startedAt);
+}
+
+/**
+ * Start a background startup task without awaiting it, and track it so that
+ * {@link awaitBackgroundTasks} can give it a chance to finish at shutdown. A rejection is
+ * logged (at debug level) and never propagated.
+ *
+ * @param id the id of the startup task.
+ * @param start starts the task.
+ */
+export function trackBackgroundTask(id: string, start: () => Promise<unknown>): void {
+  const task: InFlightTask = { id, startedAt: performance.now(), settled: Promise.resolve() };
+  logger.debug(() => `Background startup task '${id}' started`);
+  task.settled = new Promise<unknown>((resolve) => resolve(start()))
+    .then(
+      () => {
+        logger.debug(() => `Background startup task '${id}' completed in ${elapsedMs(task)}ms`);
+      },
+      (error: unknown) => {
+        logger.debug(
+          () => `Background startup task '${id}' failed after ${elapsedMs(task)}ms: ${error}`,
+        );
+      },
+    )
+    .finally(() => {
+      inFlightTasks.delete(task);
+    });
+  inFlightTasks.add(task);
+}
+
+/**
+ * Wait for the tracked background startup tasks, for at most `gracePeriodMs`. Tasks still running
+ * once it expires are abandoned. Returns immediately if no tasks are in flight. Never rejects.
+ *
+ * @param gracePeriodMs the maximum time to wait.
+ */
+export async function awaitBackgroundTasks(
+  gracePeriodMs: number = BACKGROUND_TASK_GRACE_PERIOD_MS,
+): Promise<void> {
+  if (inFlightTasks.size === 0) {
+    return;
+  }
+  const pending = [...inFlightTasks];
+  logger.debug(
+    () =>
+      `Waiting up to ${gracePeriodMs}ms for ${pending.length} in-flight background startup task(s)`,
+  );
+  for (const task of pending) {
+    logger.debug(
+      () => `Background startup task '${task.id}' still in flight after ${elapsedMs(task)}ms`,
+    );
+  }
+
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  const expired = new Promise<void>((resolve) => {
+    timer = setTimeout(resolve, gracePeriodMs);
+    // must not keep the process alive
+    (timer as { unref?: () => void }).unref?.();
+  });
+  try {
+    await Promise.race([Promise.all(pending.map((task) => task.settled)), expired]);
+  } catch {
+    // settled promises never reject; nothing to do
+  } finally {
+    clearTimeout(timer);
+  }
+
+  for (const task of pending) {
+    if (inFlightTasks.has(task)) {
+      inFlightTasks.delete(task);
+      logger.debug(
+        () =>
+          `Background startup task '${task.id}' cancelled after ${elapsedMs(task)}ms: still running when the ${gracePeriodMs}ms grace period expired`,
+      );
+    }
+  }
+}

package/src/runtime/runner.ts

@@ -33,6 +33,7 @@ import type { StartupTask } from "@flowscripter/dynamic-cli-framework-api";
 import type { ServiceProvider } from "@flowscripter/dynamic-cli-framework-api";
 import DefaultStartupService from "../service/startup/DefaultStartupService.ts";
 import { sortByPriority } from "./lifecycle/PriorityTaskList.ts";
+import { trackBackgroundTask } from "./lifecycle/BackgroundTasks.ts";
 
 const logger = getLogger("runner");
 
@@ -564,8 +565,8 @@ async function findAndExecuteDefaultNonModifierCommand(
  *    - Give the task a Context whose KeyValueService is bound permanently to its own scope
  *      (keyed by task.id), via KeyValueServiceProvider if provided.
  *    - Run the task: awaited before continuing if its mode is "blocking" (the default, and how
- *      every ServiceProvider's initService() behaves); fired without awaiting if "background"
- *      (errors logged, not propagated).
+ *      every ServiceProvider's initService() behaves); started without awaiting if "background"
+ *      (errors logged, not propagated; the CLI gives it a short grace period to finish at shutdown).
  *    - Return immediately if a "blocking" task returned an exitRequest, using its runState and
  *      skipping the remaining tasks and the command.
  * 2. Scan arguments for any GlobalModifierCommand clauses not provided by a StartupTask
@@ -698,9 +699,7 @@ export async function run(
         return { runState: outcome.exitRequest.runState, exitRequested: true };
       }
     } else {
-      void task.run(taskContext).catch((error: unknown) => {
-        logger.debug(() => `Background startup task '${task.id}' failed: ${error}`);
-      });
+      trackBackgroundTask(task.id, () => task.run(taskContext));
     }
   }