@flowscripter/dynamic-cli-framework 6.0.1 → 7.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flowscripter/dynamic-cli-framework",
-  "version": "6.0.1",
+  "version": "7.0.0",
   "description": "A framework for developing CLI applications which supports dynamic discovery and installation of new commands",
   "keywords": [
     "bun",
@@ -48,7 +48,7 @@
     "build": "tsc -p tsconfig.build.json"
   },
   "dependencies": {
-    "@flowscripter/dynamic-cli-framework-api": "^3.0.1",
+    "@flowscripter/dynamic-cli-framework-api": "^4.0.1",
     "@flowscripter/dynamic-plugin-framework": "^2.2.9",
     "emphasize": "^7.0.0",
     "fastest-levenshtein": "^1.0.16",

package/src/cli/BaseCLI.ts

@@ -28,8 +28,11 @@ import {
 } from "../runtime/command/CommandTypeGuards.ts";
 import CommandValidator from "../runtime/command/CommandValidator.ts";
 import ShutdownServiceProvider from "../service/shutdown/ShutdownServiceProvider.ts";
+import StartupServiceProvider from "../service/startup/StartupServiceProvider.ts";
+import type { StartupTask } from "@flowscripter/dynamic-cli-framework-api";
 import { shutdownState } from "../service/shutdown/ShutdownState.ts";
 import ConfigurationServiceProvider from "../service/configuration/ConfigurationServiceProvider.ts";
+import KeyValueServiceProvider from "../service/configuration/KeyValueServiceProvider.ts";
 import PrinterServiceProvider from "../service/printer/PrinterServiceProvider.ts";
 import TableGeneratorServiceProvider from "../service/tableGenerator/TableGeneratorServiceProvider.ts";
 import { run } from "../runtime/runner.ts";
@@ -53,7 +56,9 @@ import CompletionServiceProvider from "../service/completion/CompletionServicePr
 import ImagePrinterServiceProvider from "../service/imagePrinter/ImagePrinterServiceProvider.ts";
 import SpawnServiceProvider from "../service/spawn/SpawnServiceProvider.ts";
 import FetchServiceProvider from "../service/fetch/FetchServiceProvider.ts";
-import UpgradeServiceProvider from "../service/upgrade/UpgradeServiceProvider.ts";
+import UpgradeServiceProvider, {
+  createUpgradeCheckStartupTask,
+} from "../service/upgrade/UpgradeServiceProvider.ts";
 import PluginServiceProvider from "../service/plugin/PluginServiceProvider.ts";
 const logger = getLogger("BaseCLI");
 
@@ -103,6 +108,7 @@ export default class BaseCLI implements CLI {
   readonly #context: DefaultContext;
   readonly #printerService: PrinterService;
   readonly #stdoutTerminal: Terminal;
+  readonly #startupServiceProvider: StartupServiceProvider;
 
   constructor(
     cliConfig: CLIConfig,
@@ -168,6 +174,10 @@ export default class BaseCLI implements CLI {
     // create a context
     this.#context = new DefaultContext(this.#cliConfig);
 
+    // priority 95 sits between shutdown (100) and configuration (90) - it has no ordering
+    // dependency on anything since its own initService() is a no-op.
+    this.#startupServiceProvider = new StartupServiceProvider(95);
+
     this.#stdoutTerminal = stdoutTerminal;
     this.#printerService = new DefaultPrinterService(
       stdoutWritableStream,
@@ -201,6 +211,16 @@ export default class BaseCLI implements CLI {
    *
    * @param command the {@link Command} to add.
    */
+  /**
+   * Register a {@link StartupTask} to run once during CLI startup, in priority order alongside
+   * every registered {@link ServiceProvider}'s `initService()` call.
+   *
+   * @param task the {@link StartupTask} to register.
+   */
+  public addStartupTask(task: StartupTask) {
+    this.#startupServiceProvider.startupService.registerTask(task);
+  }
+
   public addCommand(command: Command) {
     if (!isGlobalModifierCommand(command)) {
       // store the command locally to help determine if this CLI will be a single or multi-command CLI
@@ -229,6 +249,7 @@ export default class BaseCLI implements CLI {
 
     // create and add core services
     this.addServiceProvider(new ShutdownServiceProvider(100));
+    this.addServiceProvider(this.#startupServiceProvider);
     this.addServiceProvider(new PrinterServiceProvider(80, this.#printerService));
     this.addServiceProvider(new TableGeneratorServiceProvider(70));
 
@@ -293,10 +314,12 @@ export default class BaseCLI implements CLI {
       );
     }
 
+    let upgradeServiceProvider: UpgradeServiceProvider | undefined;
     if (this.#options.upgradeServiceEnabled) {
       // 56 runs after Spawn(58)/Fetch(57) - whose dependencies it needs
       // but before the consumer-configured Banner/Plugin(50) priority band.
-      this.addServiceProvider(new UpgradeServiceProvider(56, this.#options.upgradeLocationsConfig));
+      upgradeServiceProvider = new UpgradeServiceProvider(56, this.#options.upgradeLocationsConfig);
+      this.addServiceProvider(upgradeServiceProvider);
     }
 
     if (this.#options.pluginServiceEnabled) {
@@ -315,10 +338,18 @@ export default class BaseCLI implements CLI {
       90,
       this.#options.envVarsSupportEnabled,
       this.#options.configFileSupportEnabled,
-      this.#options.keyValueServiceEnabled,
       this.#options.secretServiceEnabled,
     );
     this.addServiceProvider(configurationServiceProvider);
+    // priority 89 sits just below ConfigurationServiceProvider's 90 - its config-file read
+    // happens in its own initService(), before KeyValueServiceProvider's initService() runs.
+    const keyValueServiceProvider = new KeyValueServiceProvider(
+      89,
+      configurationServiceProvider,
+      this.#options.keyValueServiceEnabled,
+      this.#options.secretServiceEnabled,
+    );
+    this.addServiceProvider(keyValueServiceProvider);
 
     for (const serviceProvider of this.#serviceProviderRegistry.getServiceProviders()) {
       const serviceInfo = await serviceProvider.getServiceInfo(this.#cliConfig);
@@ -332,6 +363,19 @@ export default class BaseCLI implements CLI {
       });
     }
 
+    if (upgradeServiceProvider?.upgradeService) {
+      this.addStartupTask(createUpgradeCheckStartupTask(upgradeServiceProvider.upgradeService, 56));
+    }
+
+    // directly-registered StartupTasks (e.g. the banner task) aren't backed by a ServiceProvider,
+    // so their modifierCommands need to be added to the command registry here instead, keyed by
+    // the task's own ID.
+    for (const task of this.#startupServiceProvider.startupService.getTasks()) {
+      (task.modifierCommands ?? []).forEach((command) => {
+        this.#commandRegistry.addCommand(command, task.id);
+      });
+    }
+
     logger.debug(() => `Running with args: ${args.join(" ")}`);
 
     let helpSubCommand: SubCommand | undefined;
@@ -381,8 +425,10 @@ export default class BaseCLI implements CLI {
         this.#commandRegistry,
         this.#serviceProviderRegistry,
         configurationServiceProvider,
+        keyValueServiceProvider,
         this.#context,
         defaultCommand,
+        this.#startupServiceProvider.startupService,
       );
       // then handle the result...
       if (runResult.runState === RunState.NO_COMMAND) {

package/src/launcher.ts

@@ -6,6 +6,7 @@ import type {
   Command,
   RunResult,
   ServiceProvider,
+  StartupTask,
 } from "@flowscripter/dynamic-cli-framework-api";
 import type BaseCLIFeatureOptions from "./cli/BaseCLIFeatureOptions.ts";
 import DefaultRuntimeCLI from "./cli/DefaultRuntimeCLI.ts";
@@ -17,6 +18,7 @@ export async function launchSingleCommandCLI(
   version?: string,
   serviceProviders?: ReadonlyArray<ServiceProvider>,
   options?: BaseCLIFeatureOptions,
+  startupTasks?: ReadonlyArray<StartupTask>,
 ): Promise<RunResult> {
   if (!name) {
     name = path.basename(process.execPath);
@@ -37,7 +39,8 @@ export async function launchSingleCommandCLI(
 
   cli.addCommand(command);
 
-  serviceProviders?.forEach((service) => cli.addServiceProvider(service));
+  serviceProviders?.forEach((serviceProvider) => cli.addServiceProvider(serviceProvider));
+  startupTasks?.forEach((startupTask) => cli.addStartupTask(startupTask));
 
   return await cli.run();
 }
@@ -49,6 +52,7 @@ export async function launchMultiCommandCLI(
   version?: string,
   serviceProviders?: ReadonlyArray<ServiceProvider>,
   options?: BaseCLIFeatureOptions,
+  startupTasks?: ReadonlyArray<StartupTask>,
 ): Promise<RunResult> {
   if (!name) {
     name = path.basename(process.execPath);
@@ -69,7 +73,8 @@ export async function launchMultiCommandCLI(
 
   commands.forEach((command) => cli.addCommand(command));
 
-  serviceProviders?.forEach((service) => cli.addServiceProvider(service));
+  serviceProviders?.forEach((serviceProvider) => cli.addServiceProvider(serviceProvider));
+  startupTasks?.forEach((startupTask) => cli.addStartupTask(startupTask));
 
   return await cli.run();
 }

package/src/runtime/lifecycle/PriorityTaskList.ts

@@ -0,0 +1,34 @@
+/**
+ * Common shape shared by {@link StartupTask} and {@link ShutdownTask}: a task with an optional
+ * priority, used to order execution. Higher values run earlier. Undefined is treated as `0`.
+ */
+export interface PriorityTask {
+  readonly priority?: number;
+}
+
+/**
+ * Stably sort tasks by descending priority (default `0`). Tasks with the same priority keep
+ * their relative order in the input array.
+ */
+export function sortByPriority<T extends PriorityTask>(tasks: ReadonlyArray<T>): Array<T> {
+  return tasks
+    .map((task, index) => ({ task, index }))
+    .sort((a, b) => (b.task.priority ?? 0) - (a.task.priority ?? 0) || a.index - b.index)
+    .map((entry) => entry.task);
+}
+
+/**
+ * Internal helper shared by {@link DefaultStartupService} and {@link DefaultShutdownService}:
+ * accumulates registered tasks and returns them in priority order on demand.
+ */
+export default class PriorityTaskList<T extends PriorityTask> {
+  readonly #tasks: Array<T> = [];
+
+  public add(task: T): void {
+    this.#tasks.push(task);
+  }
+
+  public sorted(): ReadonlyArray<T> {
+    return sortByPriority(this.#tasks);
+  }
+}

package/src/runtime/runner.ts

@@ -21,6 +21,7 @@ import { scanForGlobalModifierCommandClauses, scanForNonModifierCommandClause }
 import type { ServiceProviderRegistry } from "@flowscripter/dynamic-cli-framework-api";
 import { parseGlobalCommandClause, type ParseResult, parseSubCommandClause } from "./parser.ts";
 import type ConfigurationServiceProvider from "../service/configuration/ConfigurationServiceProvider.ts";
+import type KeyValueServiceProvider from "../service/configuration/KeyValueServiceProvider.ts";
 import type { GlobalModifierCommand } from "@flowscripter/dynamic-cli-framework-api";
 import type { GroupCommand } from "@flowscripter/dynamic-cli-framework-api";
 import type { SubCommand } from "@flowscripter/dynamic-cli-framework-api";
@@ -28,9 +29,35 @@ import type { GlobalCommand } from "@flowscripter/dynamic-cli-framework-api";
 import type { Command } from "@flowscripter/dynamic-cli-framework-api";
 import type { ArgumentPrompterService } from "@flowscripter/dynamic-cli-framework-api";
 import { ARGUMENT_PROMPTER_SERVICE_ID } from "@flowscripter/dynamic-cli-framework-api";
+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";
 
 const logger = getLogger("runner");
 
+/**
+ * Wrap a {@link ServiceProvider}'s `initService()` call as a {@link StartupTask} so it can be
+ * merged with directly-registered {@link StartupTask}s (e.g. the banner task) into a single
+ * priority-ordered sequence.
+ */
+function toProviderStartupTask(
+  serviceProvider: ServiceProvider,
+  commandRegistry: CommandRegistry,
+): StartupTask {
+  return {
+    id: serviceProvider.serviceId,
+    priority: serviceProvider.servicePriority,
+    mode: "blocking",
+    modifierCommands: Array.from(
+      commandRegistry
+        .getGlobalModifierCommandsByNameProvidedByService(serviceProvider.serviceId)
+        .values(),
+    ),
+    run: (context: Context) => serviceProvider.initService(context),
+  };
+}
+
 async function attemptPromptForMissingArguments(
   parseResult: ParseResult,
   context: Context,
@@ -58,31 +85,26 @@ async function attemptPromptForMissingArguments(
  *
  * @param parseResult the {@link ParseResult} to execute.
  * @param context the {@link Context} to use.
- * @param configurationServiceProvider optional {@link ConfigurationServiceProvider} to use to get default argument values.
+ * @param keyValueServiceProvider optional {@link KeyValueServiceProvider} to use to get a scope-decorated {@link Context}.
  * @param isDefaultCommand whether the command is the default command for the CLI.
  */
 async function executeParsedCommand(
   parseResult: ParseResult,
   context: Context,
-  configurationServiceProvider: ConfigurationServiceProvider | undefined,
+  keyValueServiceProvider: KeyValueServiceProvider | undefined,
   isDefaultCommand = false,
 ): Promise<RunResult> {
   try {
     if (parseResult.groupCommand !== undefined) {
       logger.debug("Executing group command with name: %s", parseResult!.groupCommand!.name);
-      if (
-        configurationServiceProvider?.keyValueServiceEnabled ||
-        configurationServiceProvider?.secretServiceEnabled
-      ) {
-        configurationServiceProvider.setCommandKeyValueScope(parseResult!.groupCommand!.name);
-      }
-      await parseResult.groupCommand.execute(context);
-      if (
-        configurationServiceProvider?.keyValueServiceEnabled ||
-        configurationServiceProvider?.secretServiceEnabled
-      ) {
-        await configurationServiceProvider.clearKeyValueScope();
-      }
+      const groupContext = keyValueServiceProvider
+        ? keyValueServiceProvider.getContextForScope(
+            context,
+            "command",
+            parseResult!.groupCommand!.name,
+          )
+        : context;
+      await parseResult.groupCommand.execute(groupContext);
     }
 
     logger.debug(
@@ -91,26 +113,20 @@ async function executeParsedCommand(
       parseResult!.populatedArgumentValues,
     );
 
-    if (
-      configurationServiceProvider?.keyValueServiceEnabled ||
-      configurationServiceProvider?.secretServiceEnabled
-    ) {
-      configurationServiceProvider.setCommandKeyValueScope(parseResult.command.name);
-    }
+    const commandContext = keyValueServiceProvider
+      ? keyValueServiceProvider.getContextForScope(context, "command", parseResult.command.name)
+      : context;
     if (isSubCommand(parseResult.command)) {
-      await parseResult.command.execute(context, parseResult.populatedArgumentValues as Values);
+      await parseResult.command.execute(
+        commandContext,
+        parseResult.populatedArgumentValues as Values,
+      );
     } else {
       await (parseResult.command as GlobalCommand).execute(
-        context,
+        commandContext,
         parseResult.populatedArgumentValues as SingleValueType,
       );
     }
-    if (
-      configurationServiceProvider?.keyValueServiceEnabled ||
-      configurationServiceProvider?.secretServiceEnabled
-    ) {
-      await configurationServiceProvider.clearKeyValueScope();
-    }
   } catch (err) {
     if ((err as Error).message === "Interrupted") {
       throw err;
@@ -136,6 +152,7 @@ async function executeParsedCommand(
  * @param globalModifierCommandsByName a map of non-modifier {@link Command} instances by name to parse for.
  * @param globalModifierCommandsByShortAlias a map of {@link GlobalModifierCommand} instances by short alias to use when scanning.
  * @param configurationServiceProvider optional {@link ConfigurationServiceProvider} to use to get default argument values.
+ * @param keyValueServiceProvider optional {@link KeyValueServiceProvider} to use to get a scope-decorated {@link Context}.
  * @param context the {@link Context} to use.
  */
 async function findAndExecuteGlobalModifierCommands(
@@ -144,6 +161,7 @@ async function findAndExecuteGlobalModifierCommands(
   globalModifierCommandsByName: ReadonlyMap<string, GlobalModifierCommand>,
   globalModifierCommandsByShortAlias: ReadonlyMap<string, GlobalModifierCommand>,
   configurationServiceProvider: ConfigurationServiceProvider | undefined,
+  keyValueServiceProvider: KeyValueServiceProvider | undefined,
   context: Context,
 ): Promise<RunResult | undefined> {
   // build a list of GlobalModifierCommands to execute
@@ -241,11 +259,7 @@ async function findAndExecuteGlobalModifierCommands(
   );
   for (const parseResult of globalModifierCommandParseResults) {
     // execute and fast fail on error
-    const runResult = await executeParsedCommand(
-      parseResult,
-      context,
-      configurationServiceProvider,
-    );
+    const runResult = await executeParsedCommand(parseResult, context, keyValueServiceProvider);
     if (runResult.runState !== RunState.SUCCESS) {
       return runResult;
     }
@@ -261,6 +275,7 @@ async function findAndExecuteGlobalModifierCommands(
  * @param globalCommandsByShortAlias the map of {@link GlobalCommand} instances by short alias to use when scanning.
  * @param groupAndMemberCommandsByJoinedName optional map of {@link GroupCommand} and member {@link SubCommand} instances to use when scanning.
  * @param configurationServiceProvider optional {@link ConfigurationServiceProvider} to use to get default argument values.
+ * @param keyValueServiceProvider optional {@link KeyValueServiceProvider} to use to get a scope-decorated {@link Context}.
  * @param context the {@link Context} to use.
  */
 async function findAndExecuteNonModifierCommand(
@@ -272,6 +287,7 @@ async function findAndExecuteNonModifierCommand(
     | ReadonlyMap<string, { groupCommand: GroupCommand; command: SubCommand }>
     | undefined,
   configurationServiceProvider: ConfigurationServiceProvider | undefined,
+  keyValueServiceProvider: KeyValueServiceProvider | undefined,
   context: Context,
 ): Promise<RunResult | undefined> {
   let parseResult: ParseResult | undefined;
@@ -383,7 +399,7 @@ async function findAndExecuteNonModifierCommand(
     await printUnusedArgsWarning(context, unusedArgs.flat());
   }
 
-  return executeParsedCommand(parseResult, context, configurationServiceProvider);
+  return executeParsedCommand(parseResult, context, keyValueServiceProvider);
 }
 
 /**
@@ -393,6 +409,7 @@ async function findAndExecuteNonModifierCommand(
  * @param unusedArgs an array to which any unused argument sequences will be added.
  * @param defaultNonModifierCommand the default non-modifier {@link Command} to use.
  * @param configurationServiceProvider optional {@link ConfigurationServiceProvider} to use to get default argument values.
+ * @param keyValueServiceProvider optional {@link KeyValueServiceProvider} to use to get a scope-decorated {@link Context}.
  * @param context the {@link Context} to use.
  */
 async function findAndExecuteDefaultNonModifierCommand(
@@ -400,6 +417,7 @@ async function findAndExecuteDefaultNonModifierCommand(
   unusedArgs: Array<ReadonlyArray<string>>,
   defaultNonModifierCommand: Command,
   configurationServiceProvider: ConfigurationServiceProvider | undefined,
+  keyValueServiceProvider: KeyValueServiceProvider | undefined,
   context: Context,
 ): Promise<RunResult | undefined> {
   const defaultArgumentValues = configurationServiceProvider
@@ -511,7 +529,7 @@ async function findAndExecuteDefaultNonModifierCommand(
     await printUnusedArgsWarning(context, unusedArgs.flat());
   }
 
-  return executeParsedCommand(parseResult, context, configurationServiceProvider, true);
+  return executeParsedCommand(parseResult, context, keyValueServiceProvider, true);
 }
 
 /**
@@ -520,14 +538,15 @@ async function findAndExecuteDefaultNonModifierCommand(
  *
  * An overview of the logic (assuming the optional ConfigurationServiceProvider is provided):
  *
- * 1. For each ServiceProvider in servicePriority order:
- *    - Scan arguments for GlobalModifierCommand clauses provided by the ServiceProvider
+ * 1. For each StartupTask in priority order (whether backed by a ServiceProvider's
+ *    initService() or registered directly, e.g. the banner task):
+ *    - Scan arguments for GlobalModifierCommand clauses provided by the task
  *    - For each discovered clause:
  *      - Set any argument defaults from ConfigurationServiceProvider
  *      - Parse the arguments for the GlobalModifierCommand
  *      - Return on error
  *      - Add to list of GlobalModifierCommands to execute
- *    - Scan ConfigurationServiceProvider for GlobalModifierCommand clauses provided by the ServiceProvider not already found in arguments
+ *    - Scan ConfigurationServiceProvider for GlobalModifierCommand clauses provided by the task not already found in arguments
  *    - For each configured clause:
  *      - Parse the arguments for the GlobalModifierCommand
  *      - Return on error
@@ -536,14 +555,18 @@ async function findAndExecuteDefaultNonModifierCommand(
  *    - For each GlobalModifierCommand clause:
  *      - Execute the GlobalModifierCommand
  *      - Return on error
- *    - Init the ServiceProvider's service.
- * 2. Scan arguments for any GlobalModifierCommand clauses not provided by ServiceProviders
+ *    - 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).
+ * 2. Scan arguments for any GlobalModifierCommand clauses not provided by a StartupTask
  *    - For each discovered clause:
  *      - Set any argument defaults from ConfigurationServiceProvider
  *      - Parse the arguments for the GlobalModifierCommand
  *      - Return on error
  *      - Add to list of GlobalModifierCommands to execute
- * 3. Scan ConfigurationServiceProvider for GlobalModifierCommand clauses not provided by the ServiceProvider and not already found in arguments
+ * 3. Scan ConfigurationServiceProvider for GlobalModifierCommand clauses not provided by a StartupTask and not already found in arguments
  *    - For each discovered clause:
  *    - Parse the arguments for the GlobalModifierCommand
  *    - Return on error
@@ -578,6 +601,7 @@ async function findAndExecuteDefaultNonModifierCommand(
  * @param commandRegistry the {@link CommandRegistry} to use when scanning and parsing.
  * @param serviceProviderRegistry the {@link ServiceProviderRegistry} to use when scanning and parsing.
  * @param configurationServiceProvider optional {@link ConfigurationServiceProvider} to use for accessing argument defaults.
+ * @param keyValueServiceProvider optional {@link KeyValueServiceProvider} to use to get a scope-decorated {@link Context}.
  * @param context the {@link Context} in which to execute specified {@link Command} instances.
  * @param defaultCommand optional {@link SubCommand} or {@link GlobalCommand} implementation to attempt to parse arguments for and execute if
  * no non-modifier {@link Command} name is identified in the provided arguments.
@@ -587,8 +611,10 @@ export async function run(
   commandRegistry: CommandRegistry,
   serviceProviderRegistry: ServiceProviderRegistry,
   configurationServiceProvider: ConfigurationServiceProvider | undefined,
+  keyValueServiceProvider: KeyValueServiceProvider | undefined,
   context: Context,
   defaultCommand?: Command,
+  startupService?: DefaultStartupService,
 ): Promise<RunResult> {
   if (defaultCommand && !isSubCommand(defaultCommand) && !isGlobalCommand(defaultCommand)) {
     throw new Error(
@@ -601,17 +627,29 @@ export async function run(
   let availableArgs: ReadonlyArray<ReadonlyArray<string>> = [args];
   let unusedArgs: Array<ReadonlyArray<string>> = [];
 
-  // for each ServiceProvider (they are returned in servicePriority order)
-  for (const serviceProvider of serviceProviderRegistry.getServiceProviders()) {
-    // using the GlobalModifierCommands instances provided by the ServiceProvider...
-    const globalModifierCommandsByName =
-      commandRegistry.getGlobalModifierCommandsByNameProvidedByService(serviceProvider.serviceId);
-    const globalModifierCommandsByShortAlias =
-      commandRegistry.getGlobalModifierCommandsByShortAliasProvidedByService(
-        serviceProvider.serviceId,
-      );
+  // merge every ServiceProvider's initService() into a StartupTask, then combine with any
+  // directly-registered StartupTasks (e.g. the banner task) into one priority-ordered sequence
+  const startupTasks = sortByPriority<StartupTask>([
+    ...serviceProviderRegistry
+      .getServiceProviders()
+      .map((serviceProvider) => toProviderStartupTask(serviceProvider, commandRegistry)),
+    ...(startupService ? startupService.getTasks() : []),
+  ]);
+
+  for (const task of startupTasks) {
+    // using the GlobalModifierCommands instances provided by the task...
+    const globalModifierCommandsByName = new Map(
+      (task.modifierCommands ?? []).map((command) => [command.name, command]),
+    );
+    const globalModifierCommandsByShortAlias = new Map(
+      (task.modifierCommands ?? [])
+        .filter((command): command is GlobalModifierCommand & { shortAlias: string } =>
+          Boolean(command.shortAlias),
+        )
+        .map((command) => [command.shortAlias, command]),
+    );
 
-    // if there are GlobalModifierCommands provided by the ServiceProvider...
+    // if there are GlobalModifierCommands provided by the task...
     if (globalModifierCommandsByName.size > 0) {
       // ...scan arguments, parse any resulting clauses and execute any resulting parsed GlobalModifierCommands
       const runResult = await findAndExecuteGlobalModifierCommands(
@@ -620,6 +658,7 @@ export async function run(
         globalModifierCommandsByName,
         globalModifierCommandsByShortAlias,
         configurationServiceProvider,
+        keyValueServiceProvider,
         context,
       );
 
@@ -633,23 +672,20 @@ export async function run(
       unusedArgs = [];
     }
 
-    // init the service provider's service
+    logger.debug("Running startup task with ID: %s", task.id);
 
-    logger.debug("Initialising service with ID: %s", serviceProvider.serviceId);
+    // each task gets a Context whose KeyValueService is bound permanently to its own scope (keyed
+    // by task.id)
+    const taskContext = keyValueServiceProvider
+      ? keyValueServiceProvider.getContextForScope(context, "service", task.id)
+      : context;
 
-    if (
-      configurationServiceProvider?.keyValueServiceEnabled ||
-      configurationServiceProvider?.secretServiceEnabled
-    ) {
-      configurationServiceProvider.setServiceKeyValueScope(serviceProvider.serviceId);
-    }
-
-    await serviceProvider.initService(context);
-    if (
-      configurationServiceProvider?.keyValueServiceEnabled ||
-      configurationServiceProvider?.secretServiceEnabled
-    ) {
-      await configurationServiceProvider.clearKeyValueScope();
+    if ((task.mode ?? "blocking") === "blocking") {
+      await task.run(taskContext);
+    } else {
+      void task.run(taskContext).catch((error: unknown) => {
+        logger.debug(() => `Background startup task '${task.id}' failed: ${error}`);
+      });
     }
   }
 
@@ -668,6 +704,7 @@ export async function run(
       globalModifierCommandsByName,
       globalModifierCommandsByShortAlias,
       configurationServiceProvider,
+      keyValueServiceProvider,
       context,
     );
 
@@ -695,6 +732,7 @@ export async function run(
     globalCommandsByShortAlias,
     groupAndMemberCommandByJoinedName,
     configurationServiceProvider,
+    keyValueServiceProvider,
     context,
   );
 
@@ -715,6 +753,7 @@ export async function run(
       unusedArgs,
       defaultCommand,
       configurationServiceProvider,
+      keyValueServiceProvider,
       context,
     );