@flowscripter/dynamic-cli-framework 9.0.3 → 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/dist/src/service/upgrade/DefaultUpgradeService.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"DefaultUpgradeService.d.ts","sourceRoot":"","sources":["../../../../src/service/upgrade/DefaultUpgradeService.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EACV,SAAS,EACT,OAAO,EAKP,WAAW,EAEX,kBAAkB,EAClB,aAAa,EAEd,MAAM,yCAAyC,CAAC;AACjD,OAAO,EAEL,aAAa,EAGb,QAAQ,EAER,aAAa,EACb,WAAW,EACX,KAAK,cAAc,EACpB,MAAM,yCAAyC,CAAC;AAEjD,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,6BAA6B,CAAC;AAwC1E,eAAO,MAAM,uBAAuB,yBAAyB,CAAC;AAY9D,wBAAgB,0BAA0B,CAAC,MAAM,EAAE,kBAAkB,GAAG,MAAM,CAI7E;AAaD;;;;;;;;;GASG;AACH,wBAAgB,UAAU,CAAC,MAAM,EAAE,WAAW,GAAG,QAAQ,GAAG,SAAS,CAiBpE;AAQD,MAAM,CAAC,OAAO,OAAO,qBAAsB,YAAW,cAAc;;IAKlE,SAAgB,oBAAoB,EAAE,MAAM,GAAG,SAAS,CAAC;IAEzD,YAAmB,MAAM,EAAE,sBAAsB,EAAE,SAAS,EAAE,SAAS,EAItE;IAEM,UAAU,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAExC;IA4DM,qBAAqB,IAAI,OAAO,CAAC,kBAAkB,CAAC,CAe1D;IAED;;;;OAIG;IACU,wBAAwB,IAAI,OAAO,CAAC,kBAAkB,CAAC,CASnE;IAED;;;OAGG;IACU,2BAA2B,IAAI,OAAO,CAAC,kBAAkB,GAAG,SAAS,CAAC,CAWlF;IAED;;;;;OAKG;IACI,yBAAyB,CAAC,aAAa,EAAE,aAAa,GAAG,MAAM,GAAG,SAAS,CAUjF;IAoBD;;;;;;;OAOG;IACU,OAAO,CAClB,UAAU,EAAE,MAAM,EAClB,IAAI,EAAE,aAAa,CAAC,MAAM,CAAC,GAC1B,OAAO,CAAC,QAAQ,GAAG,SAAS,CAAC,CAY/B;IAEM,QAAQ,IAAI,WAAW,GAAG,SAAS,CAWzC;IAEM,UAAU,IAAI,aAAa,GAAG,SAAS,CAQ7C;IAEY,mBAAmB,CAAC,EAAE,EAAE,WAAW,GAAG,OAAO,CAAC,aAAa,GAAG,SAAS,CAAC,CAoDpF;IA2CY,eAAe,CAAC,qBAAqB,CAAC,EAAE,aAAa,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAsC/F;IAEY,OAAO,CAAC,qBAAqB,CAAC,EAAE,aAAa,GAAG,OAAO,CAAC,aAAa,CAAC,CAiDlF;CAgVF"}
+{"version":3,"file":"DefaultUpgradeService.d.ts","sourceRoot":"","sources":["../../../../src/service/upgrade/DefaultUpgradeService.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,SAAS,EACT,OAAO,EAKP,WAAW,EAEX,kBAAkB,EAClB,aAAa,EAEd,MAAM,yCAAyC,CAAC;AACjD,OAAO,EAEL,aAAa,EAGb,QAAQ,EAER,aAAa,EACb,WAAW,EACX,KAAK,cAAc,EACpB,MAAM,yCAAyC,CAAC;AAEjD,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,6BAA6B,CAAC;AAmD1E,eAAO,MAAM,uBAAuB,yBAAyB,CAAC;AAE9D,wBAAgB,0BAA0B,CAAC,MAAM,EAAE,kBAAkB,GAAG,MAAM,CAI7E;AAaD;;;;;;;;;GASG;AACH,wBAAgB,UAAU,CAAC,MAAM,EAAE,WAAW,GAAG,QAAQ,GAAG,SAAS,CAiBpE;AAED,MAAM,CAAC,OAAO,OAAO,qBAAsB,YAAW,cAAc;;IAKlE,SAAgB,oBAAoB,EAAE,MAAM,GAAG,SAAS,CAAC;IAEzD,YAAmB,MAAM,EAAE,sBAAsB,EAAE,SAAS,EAAE,SAAS,EAItE;IAEM,UAAU,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAExC;IA0BM,qBAAqB,IAAI,OAAO,CAAC,kBAAkB,CAAC,CAe1D;IAED;;;;OAIG;IACU,wBAAwB,IAAI,OAAO,CAAC,kBAAkB,CAAC,CASnE;IAED;;;OAGG;IACU,2BAA2B,IAAI,OAAO,CAAC,kBAAkB,GAAG,SAAS,CAAC,CAWlF;IAED;;;;;OAKG;IACI,yBAAyB,CAAC,aAAa,EAAE,aAAa,GAAG,MAAM,GAAG,SAAS,CAUjF;IAED;;;;;;;OAOG;IACU,OAAO,CAClB,UAAU,EAAE,MAAM,EAClB,IAAI,EAAE,aAAa,CAAC,MAAM,CAAC,GAC1B,OAAO,CAAC,QAAQ,GAAG,SAAS,CAAC,CAY/B;IAEM,QAAQ,IAAI,WAAW,GAAG,SAAS,CAWzC;IAEM,UAAU,IAAI,aAAa,GAAG,SAAS,CAQ7C;IAEY,mBAAmB,CAAC,EAAE,EAAE,WAAW,GAAG,OAAO,CAAC,aAAa,GAAG,SAAS,CAAC,CAoDpF;IA2CY,eAAe,CAAC,qBAAqB,CAAC,EAAE,aAAa,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAsC/F;IAEY,OAAO,CAAC,qBAAqB,CAAC,EAAE,aAAa,GAAG,OAAO,CAAC,aAAa,CAAC,CAgElF;CA2CF"}

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

@@ -1,10 +1,10 @@
 import process from "node:process";
-import { existsSync, realpathSync } from "node:fs";
-import { mkdtemp, rename, rm } from "node:fs/promises";
-import { tmpdir } from "node:os";
-import { basename, dirname, join } from "node:path";
 import { FETCH_SERVICE_ID, InstallMethod, KEY_VALUE_SERVICE_ID, PRINTER_SERVICE_ID, RunState, SPAWN_SERVICE_ID, SupportedArch, SupportedOs, } from "@flowscripter/dynamic-cli-framework-api";
 import semver from "semver";
+import { getLatestGithubReleaseVersion, upgradeViaGithubRelease } from "./method/githubRelease.js";
+import { getLatestHomebrewVersion, isHomebrewInstalled, isRunningFromHomebrewCellar, resolveHomebrewOptExecutable, upgradeViaHomebrew, } from "./method/homebrew.js";
+import { isLinuxScriptInstall, upgradeViaLinuxScript } from "./method/linuxScript.js";
+import { getLatestWingetVersion, isWingetInstalled, upgradeViaWinget } from "./method/winget.js";
 import getLogger from "../../util/logger.js";
 const logger = getLogger("DefaultUpgradeService");
 // KeyValueService key caching the resolved InstallMethod (see detectInstallMethod()). Stored
@@ -28,11 +28,6 @@ const CACHE_TTL_MILLIS = 24 * 60 * 60 * 1000;
 // scoped KeyValueService. The banner 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"
-        : (result.error?.message ?? `exit code ${result.exitCode}`);
-}
 export function describeUpgradeCheckResult(result) {
     return result.status === "failed"
         ? `Upgrade check result: failed - ${result.error.message}`
@@ -72,11 +67,6 @@ export function toRunState(result) {
     }
     return RunState.RUNTIME_ERROR;
 }
-const OS_LABELS = {
-    [SupportedOs.LINUX]: "Linux",
-    [SupportedOs.MACOS]: "MacOS",
-    [SupportedOs.WINDOWS]: "Windows",
-};
 export default class DefaultUpgradeService {
     #context;
     #upgradeCheckPromise;
@@ -111,36 +101,6 @@ export default class DefaultUpgradeService {
             ? 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)
-    // but left on screen on failure (so the diagnostic output remains visible).
-    async #spawnQuoted(command) {
-        const spawnService = this.#spawnService;
-        const printerService = this.#printerService;
-        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;
-    }
     getUpgradeCheckResult() {
         if (!this.#upgradeCheckPromise) {
             logger.debug(() => "Starting upgrade check");
@@ -198,28 +158,11 @@ export default class DefaultUpgradeService {
             case InstallMethod.LINUX_SCRIPT:
                 return process.execPath;
             case InstallMethod.HOMEBREW:
-                return this.#resolveHomebrewOptExecutable();
+                return resolveHomebrewOptExecutable(this.#config.homebrew);
             case InstallMethod.WINGET:
                 return undefined;
         }
     }
-    // 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>".
-    #resolveHomebrewOptExecutable() {
-        if (!this.#config.homebrew) {
-            return undefined;
-        }
-        const { formula } = this.#config.homebrew;
-        const realExecutable = this.#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;
-    }
     /**
      * Run `executable` with `args` in place of this process, with terminal input and output
      * inherited, and wait for it to exit. The child process sees the current version as its
@@ -270,13 +213,13 @@ export default class DefaultUpgradeService {
         if (process.platform === "darwin" &&
             os === SupportedOs.MACOS &&
             this.#config.homebrew &&
-            this.#isRunningFromHomebrewCellar(this.#config.homebrew.formula)) {
+            isRunningFromHomebrewCellar(this.#config.homebrew.formula)) {
             return InstallMethod.HOMEBREW;
         }
         if (process.platform === "linux" &&
             os === SupportedOs.LINUX &&
             this.#config.linuxScript &&
-            this.#isLinuxScriptInstall()) {
+            isLinuxScriptInstall()) {
             return InstallMethod.LINUX_SCRIPT;
         }
         // Everything else needs an external process spawn (`brew list`, `winget list`) to confirm -
@@ -289,13 +232,13 @@ export default class DefaultUpgradeService {
         if (process.platform === "darwin" &&
             os === SupportedOs.MACOS &&
             this.#config.homebrew &&
-            (await this.#isHomebrewInstalled())) {
+            (await isHomebrewInstalled(this.#spawnService, this.#config.homebrew))) {
             detected = InstallMethod.HOMEBREW;
         }
         else if (process.platform === "win32" &&
             os === SupportedOs.WINDOWS &&
             this.#config.winget &&
-            (await this.#isWingetInstalled())) {
+            (await isWingetInstalled(this.#spawnService, this.#config.winget))) {
             detected = InstallMethod.WINGET;
         }
         else if (this.#config.githubRelease) {
@@ -402,18 +345,20 @@ export default class DefaultUpgradeService {
             if (this.#printerService) {
                 await this.#printerService.hideSpinner();
             }
+            const spawnService = this.#spawnService;
+            const printerService = this.#printerService;
             switch (checkResult.installMethod) {
                 case InstallMethod.LINUX_SCRIPT:
-                    await this.#upgradeViaLinuxScript();
+                    await upgradeViaLinuxScript(spawnService, printerService, this.#config.linuxScript);
                     break;
                 case InstallMethod.HOMEBREW:
-                    await this.#upgradeViaHomebrew(checkResult.latestVersion);
+                    await upgradeViaHomebrew(spawnService, printerService, this.#config.homebrew, checkResult.latestVersion);
                     break;
                 case InstallMethod.WINGET:
-                    await this.#upgradeViaWinget();
+                    await upgradeViaWinget(spawnService, printerService, this.#config.winget);
                     break;
                 case InstallMethod.GITHUB_RELEASE:
-                    await this.#upgradeViaGithubRelease(checkResult.os, checkResult.arch);
+                    await upgradeViaGithubRelease(spawnService, this.#fetchService, printerService, this.#config.githubRelease, this.#cliConfig.name, checkResult.os, checkResult.arch);
                     break;
             }
             return { ok: true, oldVersion, newVersion: checkResult.latestVersion };
@@ -425,40 +370,6 @@ 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 runs to completion.
-    #isRunningFromHomebrewCellar(formula) {
-        return this.#resolveRealExecutable().includes(`/Cellar/${formula}/`);
-    }
-    #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;
-        }
-    }
-    async #isHomebrewInstalled() {
-        if (!this.#spawnService || !this.#config.homebrew) {
-            return false;
-        }
-        const result = await this.#spawnService.spawn(["brew", "list", "--versions", this.#config.homebrew.formula], { mode: "ignore", longRunning: false });
-        return result.ok;
-    }
-    async #isWingetInstalled() {
-        if (!this.#spawnService || !this.#config.winget) {
-            return false;
-        }
-        const result = await this.#spawnService.spawn(["winget", "list", "--id", this.#config.winget.packageId], { mode: "ignore", longRunning: false });
-        return result.ok;
-    }
-    #isLinuxScriptInstall() {
-        return process.execPath.startsWith("/usr/local/bin/");
-    }
     async #getLatestVersion(installMethod) {
         const cacheKey = `${LATEST_VERSION_CACHE_KEY_PREFIX}${installMethod}`;
         const keyValueService = this.#keyValueService;
@@ -481,234 +392,11 @@ export default class DefaultUpgradeService {
         switch (installMethod) {
             case InstallMethod.GITHUB_RELEASE:
             case InstallMethod.LINUX_SCRIPT:
-                return this.#getLatestGithubReleaseVersion();
+                return getLatestGithubReleaseVersion(this.#fetchService, this.#config.githubRelease);
             case InstallMethod.HOMEBREW:
-                return this.#getLatestHomebrewVersion();
+                return getLatestHomebrewVersion(this.#fetchService, this.#config.homebrew);
             case InstallMethod.WINGET:
-                return this.#getLatestWingetVersion();
-        }
-    }
-    async #getLatestGithubReleaseVersion() {
-        if (!this.#config.githubRelease) {
-            return { ok: false, error: new Error("No githubRelease location configured") };
-        }
-        if (!this.#fetchService) {
-            return { ok: false, error: new Error("FetchService is not available") };
-        }
-        const { owner, repo } = this.#config.githubRelease;
-        try {
-            // Uses the plain web redirect rather than the api.github.com REST endpoint, since the
-            // latter's unauthenticated rate limit (60 requests/hour/IP) is easily exhausted, e.g. by
-            // CI runners sharing an IP pool.
-            const response = await this.#fetchService.fetch(`https://github.com/${owner}/${repo}/releases/latest`, { redirect: "manual" });
-            const location = response.headers.get("location");
-            const version = location ? /\/releases\/tag\/v?([^/]+)$/.exec(location)?.[1] : undefined;
-            if (!version) {
-                return {
-                    ok: false,
-                    error: new Error(`Unexpected response resolving latest release for ${owner}/${repo}: HTTP ${response.status}`),
-                };
-            }
-            return { ok: true, version };
-        }
-        catch (error) {
-            return {
-                ok: false,
-                error: new Error(`Failed to fetch latest GitHub release for ${owner}/${repo}: ${error}`),
-            };
-        }
-    }
-    async #getLatestHomebrewVersion() {
-        if (!this.#config.homebrew) {
-            return { ok: false, error: new Error("No homebrew location configured") };
-        }
-        if (!this.#fetchService) {
-            return { ok: false, error: new Error("FetchService is not available") };
-        }
-        const { tap, formula } = this.#config.homebrew;
-        const [tapOwner, tapName] = tap.split("/");
-        if (!tapOwner || !tapName) {
-            return { ok: false, error: new Error(`Invalid homebrew tap '${tap}'`) };
-        }
-        try {
-            const response = await this.#fetchService.fetch(`https://raw.githubusercontent.com/${tapOwner}/homebrew-${tapName}/main/${formula}.rb`);
-            if (!response.ok) {
-                return {
-                    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}`),
-            };
-        }
-    }
-    async #getLatestWingetVersion() {
-        if (!this.#config.winget) {
-            return { ok: false, error: new Error("No winget location configured") };
-        }
-        if (!this.#spawnService) {
-            return { ok: false, error: new Error("SpawnService is not available") };
-        }
-        const lines = [];
-        const result = await this.#spawnService.spawn(["winget", "show", "--id", this.#config.winget.packageId], {
-            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") };
-    }
-    async #upgradeViaLinuxScript() {
-        const { scriptUrl } = this.#config.linuxScript;
-        const result = await this.#spawnQuoted(["sh", "-c", `curl -fsSL ${scriptUrl} | sh`]);
-        if (!result.ok) {
-            throw new Error(`Install script failed: ${describeSpawnFailure(result)}`);
-        }
-    }
-    // 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.
-    async #upgradeViaHomebrew(expectedVersion) {
-        const { tap, formula } = this.#config.homebrew;
-        const updateResult = await this.#spawnQuoted(["brew", "update"]);
-        if (!updateResult.ok) {
-            throw new Error(`brew update failed: ${describeSpawnFailure(updateResult)}`);
-        }
-        const result = await this.#spawnQuoted(["brew", "upgrade", `${tap}/${formula}`]);
-        if (!result.ok) {
-            throw new Error(`brew upgrade failed: ${describeSpawnFailure(result)}`);
-        }
-        const lines = [];
-        const listResult = await this.#spawnService.spawn(["brew", "list", "--versions", formula], {
-            mode: "wrapped",
-            longRunning: false,
-            onOutput: (line) => lines.push(line),
-        });
-        const installed = lines.join(" ").trim();
-        const installedVersions = installed.split(/\s+/).slice(1);
-        if (!listResult.ok || !installedVersions.includes(expectedVersion)) {
-            throw new Error(`brew upgrade completed but version ${expectedVersion} is not installed (installed: ${installed || "unknown"})`);
-        }
-    }
-    async #upgradeViaWinget() {
-        const { packageId } = this.#config.winget;
-        const result = await this.#spawnQuoted([
-            "winget",
-            "upgrade",
-            "--id",
-            packageId,
-            "--silent",
-            "--accept-package-agreements",
-            "--accept-source-agreements",
-        ]);
-        if (!result.ok) {
-            throw new Error(`winget upgrade failed: ${describeSpawnFailure(result)}`);
-        }
-    }
-    async #upgradeViaGithubRelease(os, arch) {
-        const { owner, repo, assetPattern } = this.#config.githubRelease;
-        // 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 this.#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 this.#spawnQuoted([
-                "powershell",
-                "-Command",
-                `Expand-Archive -Path '${archivePath}' -DestinationPath '${tmpDir}' -Force`,
-            ]);
-            if (!extractResult.ok) {
-                throw new Error("Failed to extract release archive");
-            }
-            const extractedBinary = join(tmpDir, `${this.#cliConfig.name}.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 this.#spawnService.spawn(["cmd", "/c", "del", "/f", "/q", oldPath], {
-                mode: "ignore",
-            });
-            const moveResult = await this.#spawnQuoted([
-                "cmd",
-                "/c",
-                "move",
-                "/y",
-                currentExecutable,
-                oldPath,
-            ]);
-            if (!moveResult.ok) {
-                throw new Error("Failed to move current executable aside");
-            }
-            const copyResult = await this.#spawnQuoted([
-                "cmd",
-                "/c",
-                "copy",
-                "/y",
-                extractedBinary,
-                currentExecutable,
-            ]);
-            if (!copyResult.ok) {
-                throw new Error("Failed to copy new executable into place");
-            }
-        }
-        else {
-            const extractResult = await this.#spawnQuoted(["unzip", "-o", archivePath, "-d", tmpDir]);
-            if (!extractResult.ok) {
-                throw new Error("Failed to extract release archive");
-            }
-            const extractedBinary = join(tmpDir, this.#cliConfig.name);
-            // 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, this.#cliConfig.name);
-                await Bun.write(stagingBinary, Bun.file(extractedBinary));
-                await this.#spawnService.spawn(["chmod", "+x", stagingBinary], { mode: "ignore" });
-                await rename(stagingBinary, currentExecutable);
-            }
-            finally {
-                await rm(stagingDir, { recursive: true, force: true });
-            }
+                return getLatestWingetVersion(this.#spawnService, this.#config.winget);
         }
     }
 }

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

@@ -0,0 +1,6 @@
+import { type FetchService, type PrinterService, type SpawnService, SupportedArch, SupportedOs } from "@flowscripter/dynamic-cli-framework-api";
+import type { GithubReleaseLocation } from "../UpgradeLocationsConfig.ts";
+import { type VersionLookupResult } from "./shared.ts";
+export declare function getLatestGithubReleaseVersion(fetchService: FetchService | undefined, location: GithubReleaseLocation | undefined): Promise<VersionLookupResult>;
+export declare function upgradeViaGithubRelease(spawnService: SpawnService, fetchService: FetchService, printerService: PrinterService | undefined, location: GithubReleaseLocation, cliName: string, os: SupportedOs, arch: SupportedArch): Promise<void>;
+//# sourceMappingURL=githubRelease.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"githubRelease.d.ts","sourceRoot":"","sources":["../../../../../src/service/upgrade/method/githubRelease.ts"],"names":[],"mappings":"AAIA,OAAO,EACL,KAAK,YAAY,EACjB,KAAK,cAAc,EACnB,KAAK,YAAY,EACjB,aAAa,EACb,WAAW,EACZ,MAAM,yCAAyC,CAAC;AACjD,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,8BAA8B,CAAC;AAC1E,OAAO,EAAe,KAAK,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAQpE,wBAAsB,6BAA6B,CACjD,YAAY,EAAE,YAAY,GAAG,SAAS,EACtC,QAAQ,EAAE,qBAAqB,GAAG,SAAS,GAC1C,OAAO,CAAC,mBAAmB,CAAC,CAiC9B;AAED,wBAAsB,uBAAuB,CAC3C,YAAY,EAAE,YAAY,EAC1B,YAAY,EAAE,YAAY,EAC1B,cAAc,EAAE,cAAc,GAAG,SAAS,EAC1C,QAAQ,EAAE,qBAAqB,EAC/B,OAAO,EAAE,MAAM,EACf,EAAE,EAAE,WAAW,EACf,IAAI,EAAE,aAAa,GAClB,OAAO,CAAC,IAAI,CAAC,CAgGf"}