@flowscripter/dynamic-cli-framework 9.0.4 → 9.1.1

package/dist/src/cli/BaseCLI.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"BaseCLI.d.ts","sourceRoot":"","sources":["../../../src/cli/BaseCLI.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,yCAAyC,CAAC;AACnE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAIzE,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,yCAAyC,CAAC;AAGvE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,yCAAyC,CAAC;AAC/E,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAsBzE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,yCAAyC,CAAC;AAS3E,OAAO,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AACjD,OAAO,KAAK,QAAQ,MAAM,yBAAyB,CAAC;AAGpD,OAAO,KAAK,MAAM,MAAM,uBAAuB,CAAC;AAChD,OAAO,KAAK,SAAS,MAAM,0BAA0B,CAAC;AACtD,OAAO,KAAK,qBAAqB,MAAM,4BAA4B,CAAC;AAqCpE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,MAAM,CAAC,OAAO,OAAO,OAAQ,YAAW,GAAG;;IAazC,YACE,SAAS,EAAE,SAAS,EACpB,oBAAoB,EAAE,cAAc,EACpC,oBAAoB,EAAE,cAAc,EACpC,aAAa,EAAE,OAAO,EACtB,aAAa,EAAE,OAAO,EACtB,cAAc,EAAE,QAAQ,EACxB,cAAc,EAAE,QAAQ,EACxB,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,SAAS,GAAG,SAAS,EAChC,OAAO,CAAC,EAAE,qBAAqB,EAmEhC;IAED;;;;;;;OAOG;IACI,kBAAkB,CAAC,eAAe,EAAE,eAAe,QAEzD;IAED;;;;;;;;OAQG;IACH;;;;;OAKG;IACI,cAAc,CAAC,IAAI,EAAE,WAAW,QAEtC;IAEM,UAAU,CAAC,OAAO,EAAE,OAAO,QAQjC;IAEK,GAAG,CAAC,IAAI,EAAE,aAAa,CAAC,MAAM,CAAC,GAAG,OAAO,CAAC,SAAS,CAAC,CAoQzD;CACF"}
+{"version":3,"file":"BaseCLI.d.ts","sourceRoot":"","sources":["../../../src/cli/BaseCLI.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,yCAAyC,CAAC;AACnE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAIzE,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,yCAAyC,CAAC;AAGvE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,yCAAyC,CAAC;AAC/E,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAsBzE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,yCAAyC,CAAC;AAU3E,OAAO,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AACjD,OAAO,KAAK,QAAQ,MAAM,yBAAyB,CAAC;AAGpD,OAAO,KAAK,MAAM,MAAM,uBAAuB,CAAC;AAChD,OAAO,KAAK,SAAS,MAAM,0BAA0B,CAAC;AACtD,OAAO,KAAK,qBAAqB,MAAM,4BAA4B,CAAC;AAqCpE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,MAAM,CAAC,OAAO,OAAO,OAAQ,YAAW,GAAG;;IAazC,YACE,SAAS,EAAE,SAAS,EACpB,oBAAoB,EAAE,cAAc,EACpC,oBAAoB,EAAE,cAAc,EACpC,aAAa,EAAE,OAAO,EACtB,aAAa,EAAE,OAAO,EACtB,cAAc,EAAE,QAAQ,EACxB,cAAc,EAAE,QAAQ,EACxB,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,SAAS,GAAG,SAAS,EAChC,OAAO,CAAC,EAAE,qBAAqB,EAmEhC;IAED;;;;;;;OAOG;IACI,kBAAkB,CAAC,eAAe,EAAE,eAAe,QAEzD;IAED;;;;;;;;OAQG;IACH;;;;;OAKG;IACI,cAAc,CAAC,IAAI,EAAE,WAAW,QAEtC;IAEM,UAAU,CAAC,OAAO,EAAE,OAAO,QAQjC;IAEK,GAAG,CAAC,IAAI,EAAE,aAAa,CAAC,MAAM,CAAC,GAAG,OAAO,CAAC,SAAS,CAAC,CAqQzD;CACF"}

package/dist/src/cli/BaseCLI.js

@@ -17,6 +17,7 @@ import KeyValueServiceProvider from "../service/configuration/KeyValueServicePro
 import PrinterServiceProvider from "../service/printer/PrinterServiceProvider.js";
 import TableGeneratorServiceProvider from "../service/tableGenerator/TableGeneratorServiceProvider.js";
 import { run } from "../runtime/runner.js";
+import { awaitBackgroundTasks } from "../runtime/lifecycle/BackgroundTasks.js";
 import { printRuntimeError } from "../util/runnerHelper.js";
 import { WritableStream } from "node:stream/web";
 import DefaultPrinterService from "../service/printer/DefaultPrinterService.js";
@@ -322,6 +323,7 @@ export default class BaseCLI {
             };
         }
         finally {
+            await awaitBackgroundTasks();
             await ShutdownServiceProvider.shutdown();
         }
     }

package/dist/src/runtime/lifecycle/BackgroundTasks.d.ts

@@ -0,0 +1,21 @@
+/**
+ * How long, at shutdown, to wait for in-flight "background" startup tasks before abandoning them.
+ */
+export declare const BACKGROUND_TASK_GRACE_PERIOD_MS = 1000;
+/**
+ * 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 declare function trackBackgroundTask(id: string, start: () => Promise<unknown>): void;
+/**
+ * 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 declare function awaitBackgroundTasks(gracePeriodMs?: number): Promise<void>;
+//# sourceMappingURL=BackgroundTasks.d.ts.map

package/dist/src/runtime/lifecycle/BackgroundTasks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"BackgroundTasks.d.ts","sourceRoot":"","sources":["../../../../src/runtime/lifecycle/BackgroundTasks.ts"],"names":[],"mappings":"AAIA;;GAEG;AACH,eAAO,MAAM,+BAA+B,OAAO,CAAC;AAcpD;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,GAAG,IAAI,CAkBnF;AAED;;;;;GAKG;AACH,wBAAsB,oBAAoB,CACxC,aAAa,GAAE,MAAwC,GACtD,OAAO,CAAC,IAAI,CAAC,CAsCf"}

package/dist/src/runtime/lifecycle/BackgroundTasks.js

@@ -0,0 +1,69 @@
+import getLogger from "../../util/logger.js";
+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;
+const inFlightTasks = new Set();
+function elapsedMs(task) {
+    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, start) {
+    const task = { id, startedAt: performance.now(), settled: Promise.resolve() };
+    logger.debug(() => `Background startup task '${id}' started`);
+    task.settled = new Promise((resolve) => resolve(start()))
+        .then(() => {
+        logger.debug(() => `Background startup task '${id}' completed in ${elapsedMs(task)}ms`);
+    }, (error) => {
+        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 = BACKGROUND_TASK_GRACE_PERIOD_MS) {
+    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;
+    const expired = new Promise((resolve) => {
+        timer = setTimeout(resolve, gracePeriodMs);
+        // must not keep the process alive
+        timer.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/dist/src/runtime/runner.d.ts

@@ -39,8 +39,8 @@ export type RunnerResult = RunResult & {
  *    - 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

package/dist/src/runtime/runner.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"runner.d.ts","sourceRoot":"","sources":["../../../src/runtime/runner.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,yCAAyC,CAAC;AACvE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAEzE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,yCAAyC,CAAC;AAiB/E,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,yCAAyC,CAAC;AAEvF,OAAO,KAAK,4BAA4B,MAAM,0DAA0D,CAAC;AACzG,OAAO,KAAK,uBAAuB,MAAM,qDAAqD,CAAC;AAK/F,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,yCAAyC,CAAC;AAKvE,OAAO,qBAAqB,MAAM,6CAA6C,CAAC;AAKhF;;;GAGG;AACH,MAAM,MAAM,YAAY,GAAG,SAAS,GAAG;IAAE,QAAQ,CAAC,aAAa,CAAC,EAAE,IAAI,CAAA;CAAE,CAAC;AAkfzE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2EG;AACH,wBAAsB,GAAG,CACvB,IAAI,EAAE,aAAa,CAAC,MAAM,CAAC,EAC3B,eAAe,EAAE,eAAe,EAChC,uBAAuB,EAAE,uBAAuB,EAChD,4BAA4B,EAAE,4BAA4B,GAAG,SAAS,EACtE,uBAAuB,EAAE,uBAAuB,GAAG,SAAS,EAC5D,OAAO,EAAE,OAAO,EAChB,cAAc,CAAC,EAAE,OAAO,EACxB,cAAc,CAAC,EAAE,qBAAqB,GACrC,OAAO,CAAC,YAAY,CAAC,CAoKvB"}
+{"version":3,"file":"runner.d.ts","sourceRoot":"","sources":["../../../src/runtime/runner.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,yCAAyC,CAAC;AACvE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAEzE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,yCAAyC,CAAC;AAiB/E,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,yCAAyC,CAAC;AAEvF,OAAO,KAAK,4BAA4B,MAAM,0DAA0D,CAAC;AACzG,OAAO,KAAK,uBAAuB,MAAM,qDAAqD,CAAC;AAK/F,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,yCAAyC,CAAC;AAKvE,OAAO,qBAAqB,MAAM,6CAA6C,CAAC;AAMhF;;;GAGG;AACH,MAAM,MAAM,YAAY,GAAG,SAAS,GAAG;IAAE,QAAQ,CAAC,aAAa,CAAC,EAAE,IAAI,CAAA;CAAE,CAAC;AAkfzE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2EG;AACH,wBAAsB,GAAG,CACvB,IAAI,EAAE,aAAa,CAAC,MAAM,CAAC,EAC3B,eAAe,EAAE,eAAe,EAChC,uBAAuB,EAAE,uBAAuB,EAChD,4BAA4B,EAAE,4BAA4B,GAAG,SAAS,EACtE,uBAAuB,EAAE,uBAAuB,GAAG,SAAS,EAC5D,OAAO,EAAE,OAAO,EAChB,cAAc,CAAC,EAAE,OAAO,EACxB,cAAc,CAAC,EAAE,qBAAqB,GACrC,OAAO,CAAC,YAAY,CAAC,CAkKvB"}

package/dist/src/runtime/runner.js

@@ -7,6 +7,7 @@ import { parseGlobalCommandClause, parseSubCommandClause } from "./parser.js";
 import { ARGUMENT_PROMPTER_SERVICE_ID } from "@flowscripter/dynamic-cli-framework-api";
 import DefaultStartupService from "../service/startup/DefaultStartupService.js";
 import { sortByPriority } from "./lifecycle/PriorityTaskList.js";
+import { trackBackgroundTask } from "./lifecycle/BackgroundTasks.js";
 const logger = getLogger("runner");
 /**
  * Wrap a {@link ServiceProvider}'s `initService()` call as a {@link StartupTask} so it can be
@@ -387,8 +388,8 @@ async function findAndExecuteDefaultNonModifierCommand(availableArgs, unusedArgs
  *    - 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
@@ -486,9 +487,7 @@ export async function run(args, commandRegistry, serviceProviderRegistry, config
             }
         }
         else {
-            void task.run(taskContext).catch((error) => {
-                logger.debug(() => `Background startup task '${task.id}' failed: ${error}`);
-            });
+            trackBackgroundTask(task.id, () => task.run(taskContext));
         }
     }
     // using the GlobalModifierCommands instances which are NOT provided by a ServiceProvider...

package/dist/src/util/helpHelper.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"helpHelper.d.ts","sourceRoot":"","sources":["../../../src/util/helpHelper.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,yCAAyC,CAAC;AAG7E,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,yCAAyC,CAAC;AAC1E,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,yCAAyC,CAAC;AAIvE,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,yCAAyC,CAAC;AACrF,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,yCAAyC,CAAC;AAM5E,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACzE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,yCAAyC,CAAC;AAG9E,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,yCAAyC,CAAC;AA6BrF,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,cAAc,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC,CAAC;CAC5C;AAED,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,WAAW,EAAE,KAAK,CAAC,SAAS,CAAC,CAAC;CACxC;AAsDD,wBAAsB,iBAAiB,CACrC,cAAc,EAAE,cAAc,EAC9B,qBAAqB,EAAE,qBAAqB,EAC5C,QAAQ,EAAE,KAAK,CAAC,WAAW,CAAC,GAC3B,OAAO,CAAC,IAAI,CAAC,CA2Cf;AA2BD,wBAAgB,0BAA0B,CACxC,SAAS,EAAE,SAAS,EACpB,cAAc,EAAE,OAAO,EACvB,aAAa,EAAE,aAAa,GAC3B,SAAS,CA6DX;AAED,wBAAgB,4BAA4B,CAAC,UAAU,EAAE,UAAU,GAAG,MAAM,CA+C3E;AAkLD,wBAAgB,0BAA0B,CACxC,SAAS,EAAE,SAAS,EACpB,cAAc,EAAE,OAAO,EACvB,UAAU,EAAE,UAAU,EACtB,kBAAkB,EAAE,OAAO,GAC1B,KAAK,CAAC,WAAW,CAAC,CAoBpB;AACD,wBAAgB,8BAA8B,CAC5C,cAAc,EAAE,cAAc,EAC9B,OAAO,EAAE,OAAO,EAChB,UAAU,EAAE,UAAU,GACrB,KAAK,CAAC,WAAW,CAAC,CAgCpB;AAED,wBAAgB,wBAAwB,CACtC,OAAO,EAAE,OAAO,EAChB,sBAAsB,EAAE,aAAa,CAAC,qBAAqB,CAAC,EAC5D,cAAc,EAAE,aAAa,CAAC,aAAa,CAAC,EAC5C,aAAa,EAAE,aAAa,CAAC,YAAY,CAAC,EAC1C,WAAW,EAAE,aAAa,CAAC,UAAU,CAAC,GACrC,MAAM,CA8IR;AAED,wBAAgB,wBAAwB,CACtC,WAAW,EAAE,MAAM,EACnB,aAAa,EAAE,aAAa,CAAC,YAAY,CAAC,EAC1C,WAAW,EAAE,aAAa,CAAC,UAAU,CAAC,GACrC,MAAM,EAAE,CAkBV"}
+{"version":3,"file":"helpHelper.d.ts","sourceRoot":"","sources":["../../../src/util/helpHelper.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,yCAAyC,CAAC;AAG7E,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,yCAAyC,CAAC;AAC1E,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,yCAAyC,CAAC;AAIvE,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,yCAAyC,CAAC;AACrF,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,yCAAyC,CAAC;AAM5E,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACzE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,yCAAyC,CAAC;AAG9E,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,yCAAyC,CAAC;AAiCrF,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,cAAc,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC,CAAC;CAC5C;AAED,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,WAAW,EAAE,KAAK,CAAC,SAAS,CAAC,CAAC;CACxC;AAsDD,wBAAsB,iBAAiB,CACrC,cAAc,EAAE,cAAc,EAC9B,qBAAqB,EAAE,qBAAqB,EAC5C,QAAQ,EAAE,KAAK,CAAC,WAAW,CAAC,GAC3B,OAAO,CAAC,IAAI,CAAC,CA2Cf;AA2BD,wBAAgB,0BAA0B,CACxC,SAAS,EAAE,SAAS,EACpB,cAAc,EAAE,OAAO,EACvB,aAAa,EAAE,aAAa,GAC3B,SAAS,CA6DX;AAED,wBAAgB,4BAA4B,CAAC,UAAU,EAAE,UAAU,GAAG,MAAM,CA+C3E;AAkLD,wBAAgB,0BAA0B,CACxC,SAAS,EAAE,SAAS,EACpB,cAAc,EAAE,OAAO,EACvB,UAAU,EAAE,UAAU,EACtB,kBAAkB,EAAE,OAAO,GAC1B,KAAK,CAAC,WAAW,CAAC,CAoBpB;AACD,wBAAgB,8BAA8B,CAC5C,cAAc,EAAE,cAAc,EAC9B,OAAO,EAAE,OAAO,EAChB,UAAU,EAAE,UAAU,GACrB,KAAK,CAAC,WAAW,CAAC,CAgCpB;AAED,wBAAgB,wBAAwB,CACtC,OAAO,EAAE,OAAO,EAChB,sBAAsB,EAAE,aAAa,CAAC,qBAAqB,CAAC,EAC5D,cAAc,EAAE,aAAa,CAAC,aAAa,CAAC,EAC5C,aAAa,EAAE,aAAa,CAAC,YAAY,CAAC,EAC1C,WAAW,EAAE,aAAa,CAAC,UAAU,CAAC,GACrC,MAAM,CA8IR;AAED,wBAAgB,wBAAwB,CACtC,WAAW,EAAE,MAAM,EACnB,aAAa,EAAE,aAAa,CAAC,YAAY,CAAC,EAC1C,WAAW,EAAE,aAAa,CAAC,UAAU,CAAC,GACrC,MAAM,EAAE,CAkBV"}

package/dist/src/util/helpHelper.js

@@ -10,6 +10,9 @@ const USER_INPUT_PATTERN = new RegExp(`${USER_INPUT_START}(.*?)${USER_INPUT_END}
 function userInput(value) {
     return `${USER_INPUT_START}${value}${USER_INPUT_END}`;
 }
+function userInputList(values, separator) {
+    return values.map((value) => userInput(`${value}`)).join(separator);
+}
 function renderDescription(printerService, description) {
     let rendered = "";
     let last = 0;
@@ -122,7 +125,7 @@ export function getGlobalArgumentHelpEntry(cliConfig, includeEnvVars, globalComm
     const syntax = getGlobalCommandArgumentForm(argument);
     const notesItems = [];
     if (argument.allowableValues !== undefined && argument.allowableValues.length > 0) {
-        notesItems.push(`valid values: ${userInput(argument.allowableValues.join("|"))}`);
+        notesItems.push(`valid values: ${userInputList(argument.allowableValues, "|")}`);
     }
     else {
         switch (argument.type) {
@@ -235,7 +238,7 @@ function getOptionHelpEntry(cliConfig, includeEnvVars, command, option, subEntry
     }
     else {
         if (option.allowableValues !== undefined && option.allowableValues.length > 0) {
-            notesItems.push(`valid values: ${userInput(option.allowableValues.join("|"))}`);
+            notesItems.push(`valid values: ${userInputList(option.allowableValues, "|")}`);
         }
         else {
             switch (option.type) {
@@ -265,9 +268,9 @@ function getOptionHelpEntry(cliConfig, includeEnvVars, command, option, subEntry
         notesItems.push(range);
     }
     if (option.defaultValue !== undefined) {
-        notesItems.push(`default: ${userInput(Array.isArray(option.defaultValue)
-            ? `${option.defaultValue.join(", ")}`
-            : `${option.defaultValue}`)}`);
+        notesItems.push(`default: ${Array.isArray(option.defaultValue)
+            ? userInputList(option.defaultValue, ", ")
+            : userInput(`${option.defaultValue}`)}`);
     }
     if (option.isOptional) {
         notesItems.push("optional");
@@ -303,7 +306,7 @@ function getOptionHelpEntry(cliConfig, includeEnvVars, command, option, subEntry
 function getPositionalHelpEntry(cliConfig, includeEnvVars, command, positional) {
     const notesItems = [];
     if (positional.allowableValues !== undefined && positional.allowableValues.length > 0) {
-        notesItems.push(`valid values: ${userInput(positional.allowableValues.join("|"))}`);
+        notesItems.push(`valid values: ${userInputList(positional.allowableValues, "|")}`);
     }
     else {
         switch (positional.type) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flowscripter/dynamic-cli-framework",
-  "version": "9.0.4",
+  "version": "9.1.1",
   "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));
     }
   }
 

package/src/util/helpHelper.ts

@@ -31,6 +31,10 @@ function userInput(value: string): string {
   return `${USER_INPUT_START}${value}${USER_INPUT_END}`;
 }
 
+function userInputList(values: ReadonlyArray<unknown>, separator: string): string {
+  return values.map((value) => userInput(`${value}`)).join(separator);
+}
+
 function renderDescription(printerService: PrinterService, description: string): string {
   let rendered = "";
   let last = 0;
@@ -201,7 +205,7 @@ export function getGlobalArgumentHelpEntry(
 
   const notesItems: Array<string> = [];
   if (argument.allowableValues !== undefined && argument.allowableValues.length > 0) {
-    notesItems.push(`valid values: ${userInput(argument.allowableValues.join("|"))}`);
+    notesItems.push(`valid values: ${userInputList(argument.allowableValues, "|")}`);
   } else {
     switch (argument.type) {
       case ValueTypeName.STRING:
@@ -332,7 +336,7 @@ function getOptionHelpEntry(
     });
   } else {
     if (option.allowableValues !== undefined && option.allowableValues.length > 0) {
-      notesItems.push(`valid values: ${userInput(option.allowableValues.join("|"))}`);
+      notesItems.push(`valid values: ${userInputList(option.allowableValues, "|")}`);
     } else {
       switch (option.type) {
         case ValueTypeName.STRING:
@@ -364,11 +368,11 @@ function getOptionHelpEntry(
 
   if (option.defaultValue !== undefined) {
     notesItems.push(
-      `default: ${userInput(
+      `default: ${
         Array.isArray(option.defaultValue)
-          ? `${option.defaultValue.join(", ")}`
-          : `${option.defaultValue}`,
-      )}`,
+          ? userInputList(option.defaultValue, ", ")
+          : userInput(`${option.defaultValue}`)
+      }`,
     );
   }
 
@@ -417,7 +421,7 @@ function getPositionalHelpEntry(
 ): HelpEntry {
   const notesItems: Array<string> = [];
   if (positional.allowableValues !== undefined && positional.allowableValues.length > 0) {
-    notesItems.push(`valid values: ${userInput(positional.allowableValues.join("|"))}`);
+    notesItems.push(`valid values: ${userInputList(positional.allowableValues, "|")}`);
   } else {
     switch (positional.type) {
       case ValueTypeName.STRING: