@flowscripter/dynamic-cli-framework 6.0.1 → 7.0.0

package/dist/src/runtime/runner.js

@@ -5,7 +5,25 @@ import { printCommandExecutionError, printNoCommandRecognisedError, printNoComma
 import { scanForGlobalModifierCommandClauses, scanForNonModifierCommandClause } from "./scanner.js";
 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";
 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, commandRegistry) {
+    return {
+        id: serviceProvider.serviceId,
+        priority: serviceProvider.servicePriority,
+        mode: "blocking",
+        modifierCommands: Array.from(commandRegistry
+            .getGlobalModifierCommandsByNameProvidedByService(serviceProvider.serviceId)
+            .values()),
+        run: (context) => serviceProvider.initService(context),
+    };
+}
 async function attemptPromptForMissingArguments(parseResult, context) {
     if (!context.doesServiceExist(ARGUMENT_PROMPTER_SERVICE_ID)) {
         return undefined;
@@ -30,37 +48,27 @@ async function attemptPromptForMissingArguments(parseResult, context) {
  *
  * @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, context, configurationServiceProvider, isDefaultCommand = false) {
+async function executeParsedCommand(parseResult, context, keyValueServiceProvider, isDefaultCommand = false) {
     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("Executing command with name: %s and args: %O", parseResult.command.name, 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);
+            await parseResult.command.execute(commandContext, parseResult.populatedArgumentValues);
         }
         else {
-            await parseResult.command.execute(context, parseResult.populatedArgumentValues);
-        }
-        if (configurationServiceProvider?.keyValueServiceEnabled ||
-            configurationServiceProvider?.secretServiceEnabled) {
-            await configurationServiceProvider.clearKeyValueScope();
+            await parseResult.command.execute(commandContext, parseResult.populatedArgumentValues);
         }
     }
     catch (err) {
@@ -86,9 +94,10 @@ async function executeParsedCommand(parseResult, context, configurationServicePr
  * @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(availableArgSequences, unusedArgSequences, globalModifierCommandsByName, globalModifierCommandsByShortAlias, configurationServiceProvider, context) {
+async function findAndExecuteGlobalModifierCommands(availableArgSequences, unusedArgSequences, globalModifierCommandsByName, globalModifierCommandsByShortAlias, configurationServiceProvider, keyValueServiceProvider, context) {
     // build a list of GlobalModifierCommands to execute
     const globalModifierCommandParseResults = [];
     // maintain a list of remaining GlobalModifierCommands to scan
@@ -151,7 +160,7 @@ async function findAndExecuteGlobalModifierCommands(availableArgSequences, unuse
         a.command.executePriority);
     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;
         }
@@ -166,9 +175,10 @@ async function findAndExecuteGlobalModifierCommands(availableArgSequences, unuse
  * @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(availableArgs, unusedArgs, nonModifierCommandsByName, globalCommandsByShortAlias, groupAndMemberCommandsByJoinedName, configurationServiceProvider, context) {
+async function findAndExecuteNonModifierCommand(availableArgs, unusedArgs, nonModifierCommandsByName, globalCommandsByShortAlias, groupAndMemberCommandsByJoinedName, configurationServiceProvider, keyValueServiceProvider, context) {
     let parseResult;
     const scanResult = scanForNonModifierCommandClause(availableArgs, nonModifierCommandsByName, globalCommandsByShortAlias, groupAndMemberCommandsByJoinedName);
     // add any unused args back to the list of still available args for next scan operation
@@ -248,7 +258,7 @@ async function findAndExecuteNonModifierCommand(availableArgs, unusedArgs, nonMo
     if (unusedArgs.length > 0) {
         await printUnusedArgsWarning(context, unusedArgs.flat());
     }
-    return executeParsedCommand(parseResult, context, configurationServiceProvider);
+    return executeParsedCommand(parseResult, context, keyValueServiceProvider);
 }
 /**
  * Assume provided command in use and parse arguments and execute with specified argument values if valid.
@@ -257,9 +267,10 @@ async function findAndExecuteNonModifierCommand(availableArgs, unusedArgs, nonMo
  * @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(availableArgs, unusedArgs, defaultNonModifierCommand, configurationServiceProvider, context) {
+async function findAndExecuteDefaultNonModifierCommand(availableArgs, unusedArgs, defaultNonModifierCommand, configurationServiceProvider, keyValueServiceProvider, context) {
     const defaultArgumentValues = configurationServiceProvider
         ? await configurationServiceProvider.getDefaultArgumentValues(context.cliConfig, defaultNonModifierCommand)
         : undefined;
@@ -348,7 +359,7 @@ async function findAndExecuteDefaultNonModifierCommand(availableArgs, unusedArgs
     if (unusedArgs.length > 0) {
         await printUnusedArgsWarning(context, unusedArgs.flat());
     }
-    return executeParsedCommand(parseResult, context, configurationServiceProvider, true);
+    return executeParsedCommand(parseResult, context, keyValueServiceProvider, true);
 }
 /**
  * Scan arguments and execute the parsed {@link Command} clauses with provided argument values
@@ -356,14 +367,15 @@ async function findAndExecuteDefaultNonModifierCommand(availableArgs, unusedArgs
  *
  * 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
@@ -372,14 +384,18 @@ async function findAndExecuteDefaultNonModifierCommand(availableArgs, unusedArgs
  *    - 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
@@ -414,11 +430,12 @@ async function findAndExecuteDefaultNonModifierCommand(availableArgs, unusedArgs
  * @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.
  */
-export async function run(args, commandRegistry, serviceProviderRegistry, configurationServiceProvider, context, defaultCommand) {
+export async function run(args, commandRegistry, serviceProviderRegistry, configurationServiceProvider, keyValueServiceProvider, context, defaultCommand, startupService) {
     if (defaultCommand && !isSubCommand(defaultCommand) && !isGlobalCommand(defaultCommand)) {
         throw new Error("If a default command is provided, if must be a global command or sub-command!");
     }
@@ -427,15 +444,24 @@ export async function run(args, commandRegistry, serviceProviderRegistry, config
     // this is to prevent incorrectly parsing arguments as if they were interleaved across multiple commands which is not supported
     let availableArgs = [args];
     let unusedArgs = [];
-    // 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);
-        // if there are GlobalModifierCommands provided by the ServiceProvider...
+    // 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([
+        ...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) => Boolean(command.shortAlias))
+            .map((command) => [command.shortAlias, command]));
+        // 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(availableArgs, unusedArgs, globalModifierCommandsByName, globalModifierCommandsByShortAlias, configurationServiceProvider, context);
+            const runResult = await findAndExecuteGlobalModifierCommands(availableArgs, unusedArgs, globalModifierCommandsByName, globalModifierCommandsByShortAlias, configurationServiceProvider, keyValueServiceProvider, context);
             // nothing is returned unless a command was found and there was an error, in which case return the error
             if (runResult) {
                 return runResult;
@@ -444,16 +470,19 @@ export async function run(args, commandRegistry, serviceProviderRegistry, config
             availableArgs = unusedArgs;
             unusedArgs = [];
         }
-        // init the service provider's service
-        logger.debug("Initialising service with ID: %s", serviceProvider.serviceId);
-        if (configurationServiceProvider?.keyValueServiceEnabled ||
-            configurationServiceProvider?.secretServiceEnabled) {
-            configurationServiceProvider.setServiceKeyValueScope(serviceProvider.serviceId);
+        logger.debug("Running startup task with ID: %s", task.id);
+        // 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 ((task.mode ?? "blocking") === "blocking") {
+            await task.run(taskContext);
         }
-        await serviceProvider.initService(context);
-        if (configurationServiceProvider?.keyValueServiceEnabled ||
-            configurationServiceProvider?.secretServiceEnabled) {
-            await configurationServiceProvider.clearKeyValueScope();
+        else {
+            void task.run(taskContext).catch((error) => {
+                logger.debug(() => `Background startup task '${task.id}' failed: ${error}`);
+            });
         }
     }
     // using the GlobalModifierCommands instances which are NOT provided by a ServiceProvider...
@@ -462,7 +491,7 @@ export async function run(args, commandRegistry, serviceProviderRegistry, config
     // if there are GlobalModifierCommands NOT provided by the ServiceProvider...
     if (globalModifierCommandsByName.size > 0) {
         // ...scan arguments, parse any resulting clauses and execute any resulting parsed GlobalModifierCommands
-        const runResult = await findAndExecuteGlobalModifierCommands(availableArgs, unusedArgs, globalModifierCommandsByName, globalModifierCommandsByShortAlias, configurationServiceProvider, context);
+        const runResult = await findAndExecuteGlobalModifierCommands(availableArgs, unusedArgs, globalModifierCommandsByName, globalModifierCommandsByShortAlias, configurationServiceProvider, keyValueServiceProvider, context);
         // nothing is returned unless a command was found and there was an error, in which case return the error
         if (runResult) {
             return runResult;
@@ -477,7 +506,7 @@ export async function run(args, commandRegistry, serviceProviderRegistry, config
     // and any group/member instance combinations...
     const groupAndMemberCommandByJoinedName = commandRegistry.getGroupAndMemberCommandsByJoinedName();
     // ...scan arguments, parse a resulting clause and execute a resulting parsed non-modifier Command
-    let runResult = await findAndExecuteNonModifierCommand(availableArgs, unusedArgs, nonModifierCommandsByName, globalCommandsByShortAlias, groupAndMemberCommandByJoinedName, configurationServiceProvider, context);
+    let runResult = await findAndExecuteNonModifierCommand(availableArgs, unusedArgs, nonModifierCommandsByName, globalCommandsByShortAlias, groupAndMemberCommandByJoinedName, configurationServiceProvider, keyValueServiceProvider, context);
     // nothing is returned if no command was discovered (otherwise a run result is returned)
     if (runResult) {
         return runResult;
@@ -488,7 +517,7 @@ export async function run(args, commandRegistry, serviceProviderRegistry, config
     // if default non-modifier Command provided...
     if (defaultCommand) {
         // ...assume default command name and parse resulting clauses and execute a resulting parsed non-modifier Command if found
-        runResult = await findAndExecuteDefaultNonModifierCommand(availableArgs, unusedArgs, defaultCommand, configurationServiceProvider, context);
+        runResult = await findAndExecuteDefaultNonModifierCommand(availableArgs, unusedArgs, defaultCommand, configurationServiceProvider, keyValueServiceProvider, context);
         // nothing is returned if no command was discovered (otherwise a run result is returned)
         if (runResult) {
             return runResult;

package/dist/src/service/configuration/ConfigurationServiceProvider.d.ts

@@ -1,13 +1,20 @@
 import type { ServiceInfo, ServiceProvider } from "@flowscripter/dynamic-cli-framework-api";
-import type { SingleValueType, Values, PopulatedValues, PopulatedValueType } from "@flowscripter/dynamic-cli-framework-api";
+import type { SingleValueType, Values, ValueNode, PopulatedValues, PopulatedValueType } from "@flowscripter/dynamic-cli-framework-api";
 import type { Context } from "@flowscripter/dynamic-cli-framework-api";
 import type { Command } from "@flowscripter/dynamic-cli-framework-api";
 import type { CLIConfig } from "@flowscripter/dynamic-cli-framework-api";
+export type KeyValueServiceScopeType = "command" | "service";
 /**
- * Provides:
+ * Provides configuration of default command arguments using a configuration file and/or
+ * environment variables.
  *
- * * Configuration of default command arguments using a configuration file and/or environment variables.
- * * A generic key-value store for commands and services ({@link KeyValueService}).
+ * The same configuration file also backs the raw, per-scope key-value data consumed by
+ * {@link KeyValueServiceProvider} (which holds a direct reference to this provider - see
+ * {@link getKeyValueData} and {@link flushIfDirty} - rather than looking this provider up via
+ * {@link Context}, since only {@link configLocation}/{@link setConfigLocation} are safe to expose
+ * generally; {@link getConfigString} is wired directly to {@link DumpConfigCommand} for the same
+ * reason - a full config dump would leak every other command's/service's key-value data if it
+ * were reachable through a general lookup).
  *
  * **Default Command Arguments**
  *
@@ -52,7 +59,8 @@ import type { CLIConfig } from "@flowscripter/dynamic-cli-framework-api";
  * NOTE: You may store default arguments for secrets by manually configuring secrets in your OS
  * credential store and referencing them in the config file using the sentinel format
  * `__SECRET__:<bun_secret_name>`. These values will be resolved from the OS secret store
- * before being returned as default argument values. See "Generic Key-Value Service" below.
+ * before being returned as default argument values. See {@link KeyValueServiceProvider} for the
+ * generic key-value store which uses the same secret sentinel mechanism.
  *
  * *Environment Variables*
  *
@@ -90,60 +98,6 @@ import type { CLIConfig } from "@flowscripter/dynamic-cli-framework-api";
  * * executable: `MyCLI`, command: `command1`, nested sub-argument with both levels being arrays and referring to the 2nd element of each: `arg1[1].arg2[1]`, arg2 configuration key: `BAR` => environment variable: `MYCLI_COMMAND1_ARG1_1_BAR_2`
  *
  * NOTE: Any default values from the above configuration sources will be overridden by any arguments provided on the command line.
- *
- * **Generic Key-Value Service**
- *
- * The same configuration file above is used to provide storage for the provided {@link KeyValueService}. The values
- * are stored under a top level `key-values` property. These are expected to not be modified by the user of the CLI.
- *
- * The second and third level of properties is used to scope the key-values to specific command names
- * (via {@link Command.name} values) and specific service IDs (via {@link ServiceProvider.serviceId} values).
- * Keys are strings, but values are arbitrary JSON (see {@link ValueNode}) - not limited to strings -
- * and may be deep objects or arrays.
- *
- * Any node within a value passed to {@link KeyValueService.set} can be wrapped in {@link Secret} -
- * at any depth - to have that node, and only that node, stored as an OS-native secret. When a node
- * is wrapped in {@link Secret}, its value (of any shape) is JSON-serialized and stored as a single
- * OS-native secret via Bun.secrets, with a sentinel value of the format `__SECRET__:<bun_secret_name>`
- * substituted in its place in the structure that gets stored in the config file. Everything else in
- * the value is stored as plain (unencrypted) config data. The sentinel prefix `__SECRET__:` is
- * reserved and must not be used for regular key-value data.
- *
- * Independently of how a value was written, {@link KeyValueService.get} recursively resolves any
- * string leaf - at any depth within the retrieved value - which starts with the sentinel prefix,
- * via the OS secret store. This means a secret reference may also be hand-embedded (nested
- * arbitrarily deep) directly within a plain, non-secret value in the config file.
- *
- * Secret support requires `secretServiceEnabled=true` in the constructor (which also requires
- * `configEnabled=true`).
- *
- * As an example:
- * ```
- * {
- *    "defaults": {
- *        ...
- *    },
- *    "key-values": {
- *        "commands": {
- *            "command1": {
- *               "foo1": "bar1",
- *               "foo2": "__SECRET__:command_command1_foo2",
- *               "foo3": {
- *                   "nested": ["a", "__SECRET__:command_command1_foo3_nested"]
- *               }
- *            },
- *            "command2": {
- *                "foo1": "bar3"
- *            }
- *        },
- *        "services": {
- *            "service-id-1": {
- *                "foo1": "bar"
- *            }
- *        }
- *    }
- * }
- * ```
  */
 export default class ConfigurationServiceProvider implements ServiceProvider {
     #private;
@@ -151,7 +105,6 @@ export default class ConfigurationServiceProvider implements ServiceProvider {
     readonly servicePriority: number;
     readonly envVarsEnabled: boolean;
     readonly configEnabled: boolean;
-    readonly keyValueServiceEnabled: boolean;
     readonly secretServiceEnabled: boolean;
     configLocation: string | undefined;
     defaultsData: Map<string, Values | SingleValueType>;
@@ -161,10 +114,10 @@ export default class ConfigurationServiceProvider implements ServiceProvider {
      * @param servicePriority the priority of the service.
      * @param envVarsEnabled optionally support checking env variables for default argument values.
      * @param configEnabled optionally enable configuration file support for default argument values.
-     * @param keyValueServiceEnabled optionally provide a {@link KeyValueService} implementation: `configEnabled` must be true in this case
-     * @param secretServiceEnabled optionally enable OS-native secret storage via Bun.secrets: `configEnabled` must be true in this case
+     * @param secretServiceEnabled optionally enable OS-native secret storage via Bun.secrets for resolving
+     * secrets embedded in default argument values: `configEnabled` must be true in this case
      */
-    constructor(servicePriority: number, envVarsEnabled?: boolean, configEnabled?: boolean, keyValueServiceEnabled?: boolean, secretServiceEnabled?: boolean);
+    constructor(servicePriority: number, envVarsEnabled?: boolean, configEnabled?: boolean, secretServiceEnabled?: boolean);
     getServiceInfo(cliConfig: CLIConfig): Promise<ServiceInfo>;
     setConfigLocation(configLocation: string): void;
     /**
@@ -177,30 +130,21 @@ export default class ConfigurationServiceProvider implements ServiceProvider {
      */
     getDefaultArgumentValues(cliConfig: CLIConfig, command: Command): Promise<PopulatedValues | PopulatedValueType | undefined>;
     /**
-     * Indicate that the contained {@link DefaultKeyValueService} should be set to have a scope of the provided
-     * command name.
-     *
-     * @param commandName the name of the command to scope the key-value data to.
-     *
-     * @throws {Error} if an existing scope is set.
-     */
-    setCommandKeyValueScope(commandName: string): void;
-    /**
-     * Indicate that the contained {@link DefaultKeyValueService} should be set to have a scope of the provided
-     * service ID.
-     *
-     * @param serviceId the ID of the service to scope the key-value data to.
+     * Get-or-create the underlying, raw {@link ValueNode} `Map` for the given scope - for
+     * {@link KeyValueServiceProvider}'s exclusive use, via its direct reference to this provider.
      *
-     * @throws {Error} if an existing scope is set.
+     * @param scopeType whether `scopeKey` is a command name or a service/task ID.
+     * @param scopeKey the command name or service/task ID to scope the key-value data to.
      */
-    setServiceKeyValueScope(serviceId: string): void;
+    getKeyValueData(scopeType: KeyValueServiceScopeType, scopeKey: string): Map<string, ValueNode>;
     /**
-     * Indicate that the contained {@link DefaultKeyValueService} should have any current scope cleared.
+     * Write the configuration file, if `isDirty` is true - for {@link KeyValueServiceProvider}'s
+     * exclusive use, via its direct reference to this provider, called from its shutdown-time
+     * flush task.
      *
-     * If a scope is currently set and changes have been made to the key-value data, they will be written
-     * to the current configuration location.
+     * @param isDirty whether any scoped KeyValueService has unwritten changes.
      */
-    clearKeyValueScope(): Promise<void>;
+    flushIfDirty(isDirty: boolean): Promise<void>;
     initService(context: Context): Promise<void>;
     getConfigString(): string;
 }

package/dist/src/service/configuration/ConfigurationServiceProvider.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ConfigurationServiceProvider.d.ts","sourceRoot":"","sources":["../../../../src/service/configuration/ConfigurationServiceProvider.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,yCAAyC,CAAC;AAE5F,OAAO,KAAK,EACV,eAAe,EACf,MAAM,EAEN,eAAe,EACf,kBAAkB,EACnB,MAAM,yCAAyC,CAAC;AAEjD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,yCAAyC,CAAC;AASvE,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,yCAAyC,CAAC;AAOvE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAQzE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6IG;AACH,MAAM,CAAC,OAAO,OAAO,4BAA6B,YAAW,eAAe;;IAC1E,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAwB;IAClD,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IAEjC,SAAgB,cAAc,EAAE,OAAO,CAAC;IACxC,SAAgB,aAAa,EAAE,OAAO,CAAC;IACvC,SAAgB,sBAAsB,EAAE,OAAO,CAAC;IAChD,SAAgB,oBAAoB,EAAE,OAAO,CAAC;IAGvC,cAAc,EAAE,MAAM,GAAG,SAAS,CAAC;IAKnC,YAAY,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,GAAG,eAAe,CAAC,CAAa;IAmBvE;;;;;;;;OAQG;IACH,YACE,eAAe,EAAE,MAAM,EACvB,cAAc,UAAQ,EACtB,aAAa,UAAQ,EACrB,sBAAsB,UAAQ,EAC9B,oBAAoB,UAAQ,EAa7B;IAEM,cAAc,CAAC,SAAS,EAAE,SAAS,GAAG,OAAO,CAAC,WAAW,CAAC,CAmBhE;IAEM,iBAAiB,CAAC,cAAc,EAAE,MAAM,QAE9C;IAED;;;;;;;OAOG;IACU,wBAAwB,CACnC,SAAS,EAAE,SAAS,EACpB,OAAO,EAAE,OAAO,GACf,OAAO,CAAC,eAAe,GAAG,kBAAkB,GAAG,SAAS,CAAC,CAoD3D;IAED;;;;;;;OAOG;IACI,uBAAuB,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI,CA2BxD;IAED;;;;;;;OAOG;IACI,uBAAuB,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CA2BtD;IAED;;;;;OAKG;IACU,kBAAkB,IAAI,OAAO,CAAC,IAAI,CAAC,CAmB/C;IAEY,WAAW,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CA0CxD;IA4DM,eAAe,IAAI,MAAM,CAgC/B;CACF"}
+{"version":3,"file":"ConfigurationServiceProvider.d.ts","sourceRoot":"","sources":["../../../../src/service/configuration/ConfigurationServiceProvider.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,yCAAyC,CAAC;AAE5F,OAAO,KAAK,EACV,eAAe,EACf,MAAM,EACN,SAAS,EACT,eAAe,EACf,kBAAkB,EACnB,MAAM,yCAAyC,CAAC;AAEjD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,yCAAyC,CAAC;AASvE,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,yCAAyC,CAAC;AAOvE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAQzE,MAAM,MAAM,wBAAwB,GAAG,SAAS,GAAG,SAAS,CAAC;AAkB7D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8FG;AACH,MAAM,CAAC,OAAO,OAAO,4BAA6B,YAAW,eAAe;;IAC1E,QAAQ,CAAC,SAAS,EAAE,MAAM,CAA4B;IACtD,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IAEjC,SAAgB,cAAc,EAAE,OAAO,CAAC;IACxC,SAAgB,aAAa,EAAE,OAAO,CAAC;IACvC,SAAgB,oBAAoB,EAAE,OAAO,CAAC;IAGvC,cAAc,EAAE,MAAM,GAAG,SAAS,CAAC;IAKnC,YAAY,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,GAAG,eAAe,CAAC,CAAa;IAqBvE;;;;;;;;OAQG;IACH,YACE,eAAe,EAAE,MAAM,EACvB,cAAc,UAAQ,EACtB,aAAa,UAAQ,EACrB,oBAAoB,UAAQ,EAW7B;IAEM,cAAc,CAAC,SAAS,EAAE,SAAS,GAAG,OAAO,CAAC,WAAW,CAAC,CAehE;IAEM,iBAAiB,CAAC,cAAc,EAAE,MAAM,QAE9C;IAED;;;;;;;OAOG;IACU,wBAAwB,CACnC,SAAS,EAAE,SAAS,EACpB,OAAO,EAAE,OAAO,GACf,OAAO,CAAC,eAAe,GAAG,kBAAkB,GAAG,SAAS,CAAC,CAoD3D;IAED;;;;;;OAMG;IACI,eAAe,CACpB,SAAS,EAAE,wBAAwB,EACnC,QAAQ,EAAE,MAAM,GACf,GAAG,CAAC,MAAM,EAAE,SAAS,CAAC,CAOxB;IAED;;;;;;OAMG;IACU,YAAY,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAQzD;IAEY,WAAW,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CA0CxD;IA4DM,eAAe,IAAI,MAAM,CAgC/B;CACF"}