@flowscripter/dynamic-cli-framework 9.0.4 → 9.1.0

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/package.json

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