@flowscripter/dynamic-cli-framework 6.0.0 → 7.0.0

package/dist/src/service/configuration/ConfigurationServiceProvider.js

@@ -5,19 +5,36 @@ import { Stats } from "node:fs";
 import ConfigCommand from "./command/ConfigCommand.js";
 import getLogger from "../../util/logger.js";
 import DumpConfigCommand from "./command/DumpConfigCommand.js";
-import { KEY_VALUE_SERVICE_ID, SECRET_SENTINEL_PREFIX, } from "@flowscripter/dynamic-cli-framework-api";
-import DefaultKeyValueService from "./DefaultKeyValueService.js";
+import { CONFIGURATION_SERVICE_ID, SECRET_SENTINEL_PREFIX, } from "@flowscripter/dynamic-cli-framework-api";
 import DefaultSecretService from "./DefaultSecretService.js";
 import resolveSecrets from "./resolveSecrets.js";
 import argumentValueMerge from "../../runtime/values/argumentValueMerge.js";
 import { isGlobalCommand, isGlobalModifierCommand, isSubCommand, } from "../../runtime/command/CommandTypeGuards.js";
 import { getGlobalCommandValueFromEnvVars, getSubCommandValuesFromEnvVars, } from "../../util/envVarHelper.js";
 const logger = getLogger("ConfigurationServiceProvider");
+class ConfigurationServiceImpl {
+    #provider;
+    constructor(provider) {
+        this.#provider = provider;
+    }
+    get configLocation() {
+        return this.#provider.configLocation;
+    }
+    setConfigLocation(location) {
+        this.#provider.setConfigLocation(location);
+    }
+}
 /**
- * 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**
  *
@@ -62,7 +79,8 @@ const logger = getLogger("ConfigurationServiceProvider");
  * 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*
  *
@@ -100,67 +118,12 @@ const logger = getLogger("ConfigurationServiceProvider");
  * * 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 {
-    serviceId = KEY_VALUE_SERVICE_ID;
+    serviceId = CONFIGURATION_SERVICE_ID;
     servicePriority;
     envVarsEnabled;
     configEnabled;
-    keyValueServiceEnabled;
     secretServiceEnabled;
     // the location of the currently managed configuration data
     configLocation;
@@ -168,55 +131,52 @@ export default class ConfigurationServiceProvider {
     // SingleValueType is for GlobalCommandArgument values, Values is for
     // SubCommandArgument values.
     defaultsData = new Map();
-    // the configuration data to be used by the CLI runner implementation
-    // when updating command scoped access to key-value data via the key-value service.
+    // the underlying per-scope key-value data, read from/written to the configuration file. Exposed
+    // (raw, not wrapped in a KeyValueService) only via getKeyValueData(), for KeyValueServiceProvider's
+    // exclusive use.
     #commandKeyValueData = new Map();
-    // the configuration data to be used by the CLI runner implementation
-    // when updating service scoped access to key-value data via the key-value service.
     #serviceKeyValueData = new Map();
-    // the optional service providing scope limited key-value data to commands and other services
-    #defaultKeyValueService;
-    // the optional service providing OS-native secret storage
-    #defaultSecretService;
-    #currentCommandNameKeyValueScope;
-    #currentServiceIdKeyValueScope;
+    // secret service used only to resolve secret sentinels embedded in default command argument
+    // values (getDefaultArgumentValues()) - unrelated to per-command/per-service KV scoping, so it
+    // uses its own fixed, dedicated scope prefix ("defaults"). Its scope is otherwise irrelevant,
+    // since only getSecret() (which doesn't consult scope) is ever called on it.
+    #defaultsSecretService;
+    /**
+     * A {@link ConfigurationService} view of this provider, registered in the {@link Context} under
+     * {@link CONFIGURATION_SERVICE_ID}. Its `configLocation` getter always reflects this provider's
+     * current value.
+     */
+    #configurationService;
     /**
      * Create an instance of the service provider with the specified details.
      *
      * @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, envVarsEnabled = false, configEnabled = false, keyValueServiceEnabled = false, secretServiceEnabled = false) {
-        if (!configEnabled && keyValueServiceEnabled) {
-            throw new Error("configEnabled must be true if keyValueServiceEnabled is true");
-        }
+    constructor(servicePriority, envVarsEnabled = false, configEnabled = false, secretServiceEnabled = false) {
         if (!configEnabled && secretServiceEnabled) {
             throw new Error("configEnabled must be true if secretServiceEnabled is true");
         }
         this.servicePriority = servicePriority;
         this.envVarsEnabled = envVarsEnabled;
         this.configEnabled = configEnabled;
-        this.keyValueServiceEnabled = keyValueServiceEnabled;
         this.secretServiceEnabled = secretServiceEnabled;
+        this.#configurationService = new ConfigurationServiceImpl(this);
     }
     getServiceInfo(cliConfig) {
         const commands = [];
         if (this.configEnabled) {
-            commands.push(new ConfigCommand(this, this.servicePriority));
-            commands.push(new DumpConfigCommand(this));
+            commands.push(new ConfigCommand(this.servicePriority));
+            commands.push(new DumpConfigCommand(() => this.getConfigString()));
         }
         if (this.secretServiceEnabled) {
-            this.#defaultSecretService = new DefaultSecretService(cliConfig.name);
-        }
-        if (this.keyValueServiceEnabled || this.secretServiceEnabled) {
-            this.#defaultKeyValueService = new DefaultKeyValueService(this.#defaultSecretService);
+            this.#defaultsSecretService = new DefaultSecretService(cliConfig.name, "defaults");
         }
         return Promise.resolve({
-            // this may be undefined if keyValueServiceEnabled and secretServiceEnabled are false
-            service: this.#defaultKeyValueService,
+            service: this.#configurationService,
             // this may be empty if configEnabled is false
             commands,
         });
@@ -266,9 +226,9 @@ export default class ConfigurationServiceProvider {
                 result = argumentValueMerge(envVarValues, configuredValues);
             }
         }
-        if (result !== undefined && this.#defaultSecretService) {
+        if (result !== undefined && this.#defaultsSecretService) {
             result = await resolveSecrets(result, async (bunSecretName) => {
-                const secretValue = await this.#defaultSecretService.getSecret(bunSecretName);
+                const secretValue = await this.#defaultsSecretService.getSecret(bunSecretName);
                 if (secretValue === null) {
                     throw new Error(`Secret not found in OS secret store for sentinel: '${SECRET_SENTINEL_PREFIX}${bunSecretName}'`);
                 }
@@ -278,89 +238,34 @@ export default class ConfigurationServiceProvider {
         return result;
     }
     /**
-     * Indicate that the contained {@link DefaultKeyValueService} should be set to have a scope of the provided
-     * command name.
+     * 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.
      *
-     * @param commandName the name of the command to scope the key-value data to.
-     *
-     * @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.
      */
-    setCommandKeyValueScope(commandName) {
-        if (!this.keyValueServiceEnabled && !this.secretServiceEnabled) {
-            throw new Error(`Attempt to use KeyValueService/SecretService which is not enabled`);
-        }
-        if (this.#currentCommandNameKeyValueScope) {
-            throw new Error(`Attempt to set CommandNameKeyValueScope to ${commandName} when it is currently set to ${this.#currentCommandNameKeyValueScope}`);
-        }
-        if (this.#currentServiceIdKeyValueScope) {
-            throw new Error(`Attempt to set CommandNameKeyValueScope to ${commandName} when ServiceIdKeyValueScope is currently set to ${this.#currentCommandNameKeyValueScope}`);
-        }
-        this.#currentCommandNameKeyValueScope = commandName;
-        logger.debug("currentCommandNameKeyValueScope: %s", commandName);
-        if (this.#defaultKeyValueService) {
-            if (!this.#commandKeyValueData.has(commandName)) {
-                this.#commandKeyValueData.set(commandName, new Map());
-            }
-            this.#defaultKeyValueService.setKeyValueData(this.#commandKeyValueData.get(commandName));
-        }
-        if (this.#defaultSecretService) {
-            this.#defaultSecretService.setScope("command_" + commandName);
-        }
-    }
-    /**
-     * 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.
-     *
-     * @throws {Error} if an existing scope is set.
-     */
-    setServiceKeyValueScope(serviceId) {
-        if (!this.keyValueServiceEnabled && !this.secretServiceEnabled) {
-            throw new Error(`Attempt to use KeyValueService/SecretService which is not enabled`);
-        }
-        if (this.#currentServiceIdKeyValueScope) {
-            throw new Error(`Attempt to set ServiceIdKeyValueScope to ${serviceId} when it is currently set to ${this.#currentServiceIdKeyValueScope}`);
-        }
-        if (this.#currentCommandNameKeyValueScope) {
-            throw new Error(`Attempt to set ServiceIdKeyValueScope to ${serviceId} when CommandNameKeyValueScope is currently set to ${this.#currentServiceIdKeyValueScope}`);
-        }
-        this.#currentServiceIdKeyValueScope = serviceId;
-        logger.debug("currentServiceIdKeyValueScope: %s", serviceId);
-        if (this.#defaultKeyValueService) {
-            if (!this.#serviceKeyValueData.has(serviceId)) {
-                this.#serviceKeyValueData.set(serviceId, new Map());
-            }
-            this.#defaultKeyValueService.setKeyValueData(this.#serviceKeyValueData.get(serviceId));
-        }
-        if (this.#defaultSecretService) {
-            this.#defaultSecretService.setScope("service_" + serviceId);
+    getKeyValueData(scopeType, scopeKey) {
+        const keyValueData = scopeType === "command" ? this.#commandKeyValueData : this.#serviceKeyValueData;
+        if (!keyValueData.has(scopeKey)) {
+            keyValueData.set(scopeKey, new Map());
         }
+        return keyValueData.get(scopeKey);
     }
     /**
-     * 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.
      */
-    async clearKeyValueScope() {
-        if (!this.keyValueServiceEnabled && !this.secretServiceEnabled) {
-            throw new Error(`Attempt to use KeyValueService/SecretService which is not enabled`);
-        }
-        if (this.#defaultKeyValueService && this.#defaultKeyValueService.isDirty()) {
-            if (this.configLocation === undefined) {
-                throw new Error("Attempt to write updated config with no configLocation set");
-            }
-            await this.#writeConfig(this.configLocation);
-        }
-        this.#currentCommandNameKeyValueScope = undefined;
-        this.#currentServiceIdKeyValueScope = undefined;
-        if (this.#defaultKeyValueService) {
-            this.#defaultKeyValueService.clearKeyValueData();
+    async flushIfDirty(isDirty) {
+        if (!isDirty) {
+            return;
         }
-        if (this.#defaultSecretService) {
-            this.#defaultSecretService.clearScope();
+        if (this.configLocation === undefined) {
+            throw new Error("Attempt to write updated config with no configLocation set");
         }
+        await this.#writeConfig(this.configLocation);
     }
     async initService(context) {
         if (!this.configEnabled) {

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

@@ -1,10 +1,13 @@
 import type { ValueNode, KeyValueService, SettableValueNode } from "@flowscripter/dynamic-cli-framework-api";
 import type DefaultSecretService from "./DefaultSecretService.ts";
+/**
+ * Bound permanently to a single scope's data at construction - never re-pointed afterward. Create
+ * a separate instance per scope (see {@link KeyValueServiceProvider.getScopedKeyValueService}),
+ * rather than sharing one instance across scopes.
+ */
 export default class DefaultKeyValueService implements KeyValueService {
     #private;
-    constructor(secretService?: DefaultSecretService);
-    setKeyValueData(keyValueData: Map<string, ValueNode>): void;
-    clearKeyValueData(): void;
+    constructor(keyValueData: Map<string, ValueNode>, secretService?: DefaultSecretService);
     isDirty(): boolean;
     get<T extends ValueNode = ValueNode>(key: string): Promise<T>;
     has(key: string): Promise<boolean>;

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

@@ -1 +1 @@
-{"version":3,"file":"DefaultKeyValueService.d.ts","sourceRoot":"","sources":["../../../../src/service/configuration/DefaultKeyValueService.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,SAAS,EACT,eAAe,EACf,iBAAiB,EAClB,MAAM,yCAAyC,CAAC;AAEjD,OAAO,KAAK,oBAAoB,MAAM,2BAA2B,CAAC;AAGlE,MAAM,CAAC,OAAO,OAAO,sBAAuB,YAAW,eAAe;;IAKpE,YAAY,aAAa,CAAC,EAAE,oBAAoB,EAE/C;IAEM,eAAe,CAAC,YAAY,EAAE,GAAG,CAAC,MAAM,EAAE,SAAS,CAAC,QAM1D;IAEM,iBAAiB,SAGvB;IAEM,OAAO,IAAI,OAAO,CAExB;IAEY,GAAG,CAAC,CAAC,SAAS,SAAS,GAAG,SAAS,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC,CAyBzE;IAEM,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAKxC;IAEY,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC,CAMrE;IAsCY,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAU9C;CAsBF"}
+{"version":3,"file":"DefaultKeyValueService.d.ts","sourceRoot":"","sources":["../../../../src/service/configuration/DefaultKeyValueService.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,SAAS,EACT,eAAe,EACf,iBAAiB,EAClB,MAAM,yCAAyC,CAAC;AAEjD,OAAO,KAAK,oBAAoB,MAAM,2BAA2B,CAAC;AAGlE;;;;GAIG;AACH,MAAM,CAAC,OAAO,OAAO,sBAAuB,YAAW,eAAe;;IAKpE,YAAY,YAAY,EAAE,GAAG,CAAC,MAAM,EAAE,SAAS,CAAC,EAAE,aAAa,CAAC,EAAE,oBAAoB,EAGrF;IAEM,OAAO,IAAI,OAAO,CAExB;IAEY,GAAG,CAAC,CAAC,SAAS,SAAS,GAAG,SAAS,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC,CAsBzE;IAEM,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAExC;IAEY,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC,CAGrE;IAsCY,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAO9C;CAsBF"}

package/dist/src/service/configuration/DefaultKeyValueService.js

@@ -1,30 +1,22 @@
 import { Secret, SECRET_SENTINEL_PREFIX } from "@flowscripter/dynamic-cli-framework-api";
 import resolveSecrets from "./resolveSecrets.js";
+/**
+ * Bound permanently to a single scope's data at construction - never re-pointed afterward. Create
+ * a separate instance per scope (see {@link KeyValueServiceProvider.getScopedKeyValueService}),
+ * rather than sharing one instance across scopes.
+ */
 export default class DefaultKeyValueService {
     #keyValueData;
     #dirty = false;
     #secretService;
-    constructor(secretService) {
-        this.#secretService = secretService;
-    }
-    setKeyValueData(keyValueData) {
-        if (this.#keyValueData) {
-            throw new Error("Attempt to overwrite key-value data, it should be cleared first");
-        }
+    constructor(keyValueData, secretService) {
         this.#keyValueData = keyValueData;
-        this.#dirty = false;
-    }
-    clearKeyValueData() {
-        this.#keyValueData = undefined;
-        this.#dirty = false;
+        this.#secretService = secretService;
     }
     isDirty() {
         return this.#dirty;
     }
     async get(key) {
-        if (this.#keyValueData === undefined) {
-            throw new Error("Attempt to access undefined key-value data");
-        }
         const value = this.#keyValueData.get(key);
         if (value === undefined) {
             throw new Error("Attempt to access unknown key");
@@ -47,15 +39,9 @@ export default class DefaultKeyValueService {
         return resolveSecrets(value, resolveSecret);
     }
     has(key) {
-        if (this.#keyValueData === undefined) {
-            return Promise.reject(new Error("Attempt to access undefined key-value data"));
-        }
         return Promise.resolve(this.#keyValueData.has(key));
     }
     async set(key, value) {
-        if (this.#keyValueData === undefined) {
-            throw new Error("Attempt to access undefined key-value data");
-        }
         this.#keyValueData.set(key, await this.#storeSecrets(key, value, []));
         this.#dirty = true;
     }
@@ -88,9 +74,6 @@ export default class DefaultKeyValueService {
         return value;
     }
     async delete(key) {
-        if (this.#keyValueData === undefined) {
-            throw new Error("Attempt to access undefined key-value data");
-        }
         const value = this.#keyValueData.get(key);
         if (value !== undefined) {
             await this.#deleteSecrets(value);

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

@@ -16,9 +16,7 @@ export interface SecretsApi {
 }
 export default class DefaultSecretService implements SecretService {
     #private;
-    constructor(serviceName: string, secretsApi?: SecretsApi);
-    setScope(scope: string): void;
-    clearScope(): void;
+    constructor(serviceName: string, scope: string, secretsApi?: SecretsApi);
     setSecret(key: string, value: string): Promise<string>;
     getSecret(bunSecretName: string): Promise<string | null>;
     deleteSecret(bunSecretName: string): Promise<boolean>;

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

@@ -1 +1 @@
-{"version":3,"file":"DefaultSecretService.d.ts","sourceRoot":"","sources":["../../../../src/service/configuration/DefaultSecretService.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,yCAAyC,CAAC;AAM7E,MAAM,WAAW,UAAU;IACzB,GAAG,CAAC,OAAO,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IACxE,GAAG,CAAC,OAAO,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC9E,MAAM,CAAC,OAAO,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CACtE;AAED,MAAM,CAAC,OAAO,OAAO,oBAAqB,YAAW,aAAa;;IAKhE,YAAY,WAAW,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,UAAU,EAQvD;IAMM,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAEnC;IAEM,UAAU,IAAI,IAAI,CAExB;IAEY,SAAS,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAiBlE;IAEY,SAAS,CAAC,aAAa,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAKpE;IAEY,YAAY,CAAC,aAAa,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAKjE;IAEY,SAAS,CAAC,aAAa,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAO9D;CACF"}
+{"version":3,"file":"DefaultSecretService.d.ts","sourceRoot":"","sources":["../../../../src/service/configuration/DefaultSecretService.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,yCAAyC,CAAC;AAM7E,MAAM,WAAW,UAAU;IACzB,GAAG,CAAC,OAAO,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IACxE,GAAG,CAAC,OAAO,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC9E,MAAM,CAAC,OAAO,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CACtE;AAED,MAAM,CAAC,OAAO,OAAO,oBAAqB,YAAW,aAAa;;IAKhE,YAAY,WAAW,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,UAAU,EAStE;IAMY,SAAS,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAclE;IAEY,SAAS,CAAC,aAAa,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAKpE;IAEY,YAAY,CAAC,aAAa,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAKjE;IAEY,SAAS,CAAC,aAAa,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAO9D;CACF"}

package/dist/src/service/configuration/DefaultSecretService.js

@@ -5,26 +5,18 @@ export default class DefaultSecretService {
     #serviceName;
     #secrets;
     #scope;
-    constructor(serviceName, secretsApi) {
+    constructor(serviceName, scope, secretsApi) {
         this.#serviceName = DefaultSecretService.#sanitize(serviceName);
         if (this.#serviceName.length > MAX_NAME_LENGTH) {
             throw new Error(`Service name exceeds ${MAX_NAME_LENGTH} characters after sanitization: '${this.#serviceName}'`);
         }
+        this.#scope = DefaultSecretService.#sanitize(scope);
         this.#secrets = secretsApi ?? bunSecrets;
     }
     static #sanitize(value) {
         return value.replace(/[^a-zA-Z0-9_]/g, "_");
     }
-    setScope(scope) {
-        this.#scope = DefaultSecretService.#sanitize(scope);
-    }
-    clearScope() {
-        this.#scope = undefined;
-    }
     async setSecret(key, value) {
-        if (this.#scope === undefined) {
-            throw new Error("Attempt to set secret without a scope being set");
-        }
         const name = this.#scope + "_" + DefaultSecretService.#sanitize(key);
         if (name.length > MAX_NAME_LENGTH) {
             throw new Error(`Secret name exceeds ${MAX_NAME_LENGTH} characters: '${name}'`);

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

@@ -0,0 +1,105 @@
+import type { ServiceInfo, ServiceProvider } from "@flowscripter/dynamic-cli-framework-api";
+import type { Context } from "@flowscripter/dynamic-cli-framework-api";
+import type { CLIConfig } from "@flowscripter/dynamic-cli-framework-api";
+import type { KeyValueService } from "@flowscripter/dynamic-cli-framework-api";
+import type ConfigurationServiceProvider from "./ConfigurationServiceProvider.ts";
+import type { KeyValueServiceScopeType } from "./ConfigurationServiceProvider.ts";
+/**
+ * Provides a generic, per-scope key-value store for commands and services ({@link KeyValueService}).
+ *
+ * The underlying data is read from/written to the same configuration file managed by
+ * {@link ConfigurationServiceProvider} - see {@link ConfigurationServiceProvider.getKeyValueData} and
+ * {@link ConfigurationServiceProvider.flushIfDirty}, reached via a direct constructor reference wired
+ * up by `BaseCLI` (never via {@link Context}, since that would expose config-file read/write access
+ * more broadly than intended).
+ *
+ * Its `serviceId` is {@link KEY_VALUE_SERVICE_ID} and its {@link ServiceInfo.service} is a
+ * placeholder ({@link UnreachableKeyValueService}) - real access always goes through a per-consumer
+ * decorated {@link Context} from {@link getContextForScope}, applied by `runner.ts`.
+ *
+ * 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
+ * `keyValueServiceEnabled=true` on the {@link ConfigurationServiceProvider} to have config enabled).
+ *
+ * As an example of the underlying config file structure:
+ * ```
+ * {
+ *    "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 KeyValueServiceProvider implements ServiceProvider {
+    #private;
+    readonly serviceId: string;
+    readonly servicePriority: number;
+    readonly keyValueServiceEnabled: boolean;
+    readonly secretServiceEnabled: boolean;
+    /**
+     * Create an instance of the service provider with the specified details.
+     *
+     * @param servicePriority the priority of the service.
+     * @param configurationServiceProvider the {@link ConfigurationServiceProvider} whose config file
+     * backs this provider's data - an internal wiring reference, never exposed further.
+     * @param keyValueServiceEnabled optionally provide a {@link KeyValueService} implementation: `configurationServiceProvider.configEnabled` must be true in this case
+     * @param secretServiceEnabled optionally enable OS-native secret storage via Bun.secrets: `configurationServiceProvider.configEnabled` must be true in this case
+     */
+    constructor(servicePriority: number, configurationServiceProvider: ConfigurationServiceProvider, keyValueServiceEnabled?: boolean, secretServiceEnabled?: boolean);
+    getServiceInfo(cliConfig: CLIConfig): Promise<ServiceInfo>;
+    /**
+     * Return the {@link KeyValueService} bound to the given scope, creating (and caching) it on
+     * first request. The returned instance is permanently bound to that scope's data and secret
+     * prefix - it is never re-pointed, so it may be held and used for as long as its owning
+     * command/service/task is alive without racing any other scope's window.
+     *
+     * @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.
+     *
+     * @throws {Error} if neither `keyValueServiceEnabled` nor `secretServiceEnabled` is set.
+     */
+    getScopedKeyValueService(scopeType: KeyValueServiceScopeType, scopeKey: string): KeyValueService;
+    /**
+     * Return a {@link Context} which delegates every lookup to `context` unchanged, except
+     * `getServiceById(KEY_VALUE_SERVICE_ID)`, which resolves to the scope-bound instance from
+     * {@link getScopedKeyValueService} for the given scope. Used by `runner.ts` to give each
+     * command/service/task a KeyValueService isolated to its own scope, invisibly at the call site.
+     *
+     * Returns `context` itself, unchanged, if neither `keyValueServiceEnabled` nor
+     * `secretServiceEnabled` is set.
+     */
+    getContextForScope(context: Context, scopeType: KeyValueServiceScopeType, scopeKey: string): Context;
+    initService(context: Context): Promise<void>;
+}
+//# sourceMappingURL=KeyValueServiceProvider.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"KeyValueServiceProvider.d.ts","sourceRoot":"","sources":["../../../../src/service/configuration/KeyValueServiceProvider.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,yCAAyC,CAAC;AAC5F,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,yCAAyC,CAAC;AACvE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACzE,OAAO,KAAK,EACV,eAAe,EAGhB,MAAM,yCAAyC,CAAC;AAIjD,OAAO,KAAK,4BAA4B,MAAM,mCAAmC,CAAC;AAClF,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,mCAAmC,CAAC;AA8BlF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwDG;AACH,MAAM,CAAC,OAAO,OAAO,uBAAwB,YAAW,eAAe;;IACrE,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAwB;IAClD,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IAIjC,SAAgB,sBAAsB,EAAE,OAAO,CAAC;IAChD,SAAgB,oBAAoB,EAAE,OAAO,CAAC;IAW9C;;;;;;;;OAQG;IACH,YACE,eAAe,EAAE,MAAM,EACvB,4BAA4B,EAAE,4BAA4B,EAC1D,sBAAsB,UAAQ,EAC9B,oBAAoB,UAAQ,EAY7B;IAEM,cAAc,CAAC,SAAS,EAAE,SAAS,GAAG,OAAO,CAAC,WAAW,CAAC,CAUhE;IAED;;;;;;;;;;OAUG;IACI,wBAAwB,CAC7B,SAAS,EAAE,wBAAwB,EACnC,QAAQ,EAAE,MAAM,GACf,eAAe,CAsBjB;IAED;;;;;;;;OAQG;IACI,kBAAkB,CACvB,OAAO,EAAE,OAAO,EAChB,SAAS,EAAE,wBAAwB,EACnC,QAAQ,EAAE,MAAM,GACf,OAAO,CAWT;IAeY,WAAW,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAWxD;CACF"}