@flowscripter/dynamic-cli-framework 12.0.1 → 12.2.0

package/src/service/configuration/ConfigurationServiceProvider.ts

@@ -1,7 +1,3 @@
-import process from "node:process";
-import path from "node:path";
-import fs from "node:fs/promises";
-import { Stats } from "node:fs";
 import type { ServiceInfo, ServiceProvider } from "@flowscripter/dynamic-cli-framework-api";
 import ConfigCommand from "./command/ConfigCommand.ts";
 import type {
@@ -13,16 +9,23 @@ import type {
 } from "@flowscripter/dynamic-cli-framework-api";
 import getLogger from "../../util/logger.ts";
 import type { Context } from "@flowscripter/dynamic-cli-framework-api";
-import type { GroupCommand } from "@flowscripter/dynamic-cli-framework-api";
+import type { SubCommand, GroupCommand } from "@flowscripter/dynamic-cli-framework-api";
 import ConfigDumpSubCommand from "./command/ConfigDumpSubCommand.ts";
 import ConfigGroupCommand from "./command/ConfigGroupCommand.ts";
+import ConfigGetSubCommand from "./command/ConfigGetSubCommand.ts";
+import ConfigSetSubCommand from "./command/ConfigSetSubCommand.ts";
+import ConfigUnsetSubCommand from "./command/ConfigUnsetSubCommand.ts";
+import type { CommandRegistry } from "@flowscripter/dynamic-cli-framework-api";
 import {
   CONFIGURATION_SERVICE_ID,
-  SECRET_SENTINEL_PREFIX,
+  type ConfigurationService,
 } from "@flowscripter/dynamic-cli-framework-api";
-import type { ConfigurationService } from "@flowscripter/dynamic-cli-framework-api";
-import DefaultSecretService from "./DefaultSecretService.ts";
-import resolveSecrets from "./resolveSecrets.ts";
+import DefaultConfigurationService, {
+  type KeyValueServiceScopeType,
+} from "./DefaultConfigurationService.ts";
+import DefaultSecretService, { type SecretsApi } from "./DefaultSecretService.ts";
+import type ConfigFormat from "./format/ConfigFormat.ts";
+import jsonFormat from "./format/JsonConfigFormat.ts";
 import type { Command } from "@flowscripter/dynamic-cli-framework-api";
 import argumentValueMerge from "../../runtime/values/argumentValueMerge.ts";
 import {
@@ -36,23 +39,29 @@ import {
   getSubCommandValuesFromEnvVars,
 } from "../../util/envVarHelper.ts";
 
-const logger = getLogger("ConfigurationServiceProvider");
+export type { KeyValueServiceScopeType };
 
-export type KeyValueServiceScopeType = "command" | "service";
+const logger = getLogger("ConfigurationServiceProvider");
 
-class ConfigurationServiceImpl implements ConfigurationService {
-  readonly #provider: ConfigurationServiceProvider;
+/**
+ * The only view of the configuration which is registered in the {@link Context}, and therefore reachable by
+ * every command and service. It deliberately exposes nothing but the config file location: the
+ * {@link DefaultConfigurationService} (default values, per-scope key-value data, secret resolution and
+ * persistence) is only handed to the `config` group commands and {@link KeyValueServiceProvider}.
+ */
+class ConfigurationLocationService implements ConfigurationService {
+  readonly #service: DefaultConfigurationService;
 
-  public constructor(provider: ConfigurationServiceProvider) {
-    this.#provider = provider;
+  public constructor(service: DefaultConfigurationService) {
+    this.#service = service;
   }
 
   public get configLocation(): string | undefined {
-    return this.#provider.configLocation;
+    return this.#service.configLocation;
   }
 
   public setConfigLocation(location: string): void {
-    this.#provider.setConfigLocation(location);
+    this.#service.setConfigLocation(location);
   }
 }
 
@@ -62,11 +71,9 @@ class ConfigurationServiceImpl implements ConfigurationService {
  *
  * 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 ConfigDumpSubCommand} 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).
+ * {@link getKeyValueData} and {@link flushIfDirty}). The configuration data and its persistence are
+ * owned by {@link DefaultConfigurationService}, which is passed directly to the `config` group commands. Only a
+ * view exposing the config file location is registered under {@link CONFIGURATION_SERVICE_ID}.
  *
  * **Default Command Arguments**
  *
@@ -77,7 +84,7 @@ class ConfigurationServiceImpl implements ConfigurationService {
  *
  * *Configuration File*
  *
- * A JSON file where the structure matches {@link Values} and the defaults are stored
+ * A file (JSON by default, see {@link ConfigFormat}) where the structure matches {@link Values} and the defaults are stored
  * under a top level `defaults` property. The second level of properties is used to refer to {@link Command.name}
  * (or `<group name>:<member name>` for a member of a {@link GroupCommand}) and the contained values are treated as
  * command {@link Values}. As an example:
@@ -108,14 +115,19 @@ class ConfigurationServiceImpl implements ConfigurationService {
  * }
  * ```
  *
- * The default location of the configuration file is `$HOME/.<application_name>.json`. If `$HOME` is not defined no
+ * The syntax of the file is set by the `configFormat` constructor argument: JSON (the default), or YAML or TOML
+ * from the `yaml` and `toml` entry points of this package. The format is never inferred from the file name or
+ * extension and existing files are not migrated between formats. For YAML and TOML, comments and layout in the
+ * existing file are preserved when it is written back.
+ *
+ * The default location of the configuration file is `$HOME/.<application_name>.<format extension>`. If `$HOME` is not defined no
  * default configuration will be used. The location of the configuration file can be modified via the
  * {@link ConfigCommand}.
  *
- * 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 {@link KeyValueServiceProvider} for the
+ * NOTE: Secrets in default arguments are referenced in the config file or an environment variable using
+ * the sentinel format `__SECRET__:<bun_secret_name>` and resolved from the OS secret store before being
+ * returned as default argument values. A command's defaults may only reference secrets stored for that
+ * command via `config set` (named `defaults_Z<command>_Z<option path>`, each part escaped). See {@link KeyValueServiceProvider} for the
  * generic key-value store which uses the same secret sentinel mechanism.
  *
  * *Environment Variables*
@@ -164,33 +176,17 @@ export default class ConfigurationServiceProvider implements ServiceProvider {
   public readonly envVarsEnabled: boolean;
   public readonly configEnabled: boolean;
   public readonly secretServiceEnabled: boolean;
-
-  // the location of the currently managed configuration data
-  public configLocation: string | undefined;
-
-  // the configuration data to be used by the CLI runner implementation when setting command defaults.
-  // SingleValueType is for GlobalCommandArgument values, Values is for
-  // SubCommandArgument values.
-  public defaultsData: Map<string, Values | SingleValueType> = new Map();
-
-  // 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<string, Map<string, ValueNode>>();
-  #serviceKeyValueData = new Map<string, Map<string, ValueNode>>();
-
-  // 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: DefaultSecretService | undefined;
+  public readonly configFormat: ConfigFormat;
 
   /**
-   * 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.
+   * The {@link DefaultConfigurationService} which owns the configuration data. It is never registered
+   * in the {@link Context}: it is handed directly to the `config` group commands only.
    */
-  readonly #configurationService: ConfigurationService;
+  readonly #configurationService: DefaultConfigurationService;
+
+  readonly #hasCommandRegistry: boolean;
+
+  readonly #secretsApi: SecretsApi | undefined;
 
   /**
    * Create an instance of the service provider with the specified details.
@@ -200,12 +196,19 @@ export default class ConfigurationServiceProvider implements ServiceProvider {
    * @param configEnabled optionally enable configuration file support for default argument values.
    * @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
+   * @param configFormat optionally set the syntax of the configuration file, defaults to JSON.
+   * @param commandRegistry optionally provide the registry of all commands, required for the `config:get`,
+   * `config:set` and `config:unset` commands to be provided.
+   * @param secretsApi optionally override the OS secret store used for storing SECRET default values.
    */
   public constructor(
     servicePriority: number,
     envVarsEnabled = false,
     configEnabled = false,
     secretServiceEnabled = false,
+    configFormat: ConfigFormat = jsonFormat,
+    commandRegistry?: CommandRegistry,
+    secretsApi?: SecretsApi,
   ) {
     if (!configEnabled && secretServiceEnabled) {
       throw new Error("configEnabled must be true if secretServiceEnabled is true");
@@ -214,8 +217,15 @@ export default class ConfigurationServiceProvider implements ServiceProvider {
     this.envVarsEnabled = envVarsEnabled;
     this.configEnabled = configEnabled;
     this.secretServiceEnabled = secretServiceEnabled;
-
-    this.#configurationService = new ConfigurationServiceImpl(this);
+    this.configFormat = configFormat;
+    this.#hasCommandRegistry = commandRegistry !== undefined;
+    this.#secretsApi = secretsApi;
+
+    this.#configurationService = new DefaultConfigurationService(
+      envVarsEnabled,
+      configFormat,
+      commandRegistry,
+    );
   }
 
   public getServiceInfo(cliConfig: CLIConfig): Promise<ServiceInfo> {
@@ -223,22 +233,53 @@ export default class ConfigurationServiceProvider implements ServiceProvider {
 
     if (this.configEnabled) {
       commands.push(new ConfigCommand(this.servicePriority));
-      commands.push(
-        new ConfigGroupCommand([new ConfigDumpSubCommand(() => this.getConfigString())]),
-      );
+      const members: Array<SubCommand> = [new ConfigDumpSubCommand(this.#configurationService)];
+      if (this.#hasCommandRegistry) {
+        members.push(
+          new ConfigGetSubCommand(this.#configurationService),
+          new ConfigSetSubCommand(this.#configurationService),
+          new ConfigUnsetSubCommand(this.#configurationService),
+        );
+      }
+      commands.push(new ConfigGroupCommand(members));
     }
     if (this.secretServiceEnabled) {
-      this.#defaultsSecretService = new DefaultSecretService(cliConfig.name, "defaults");
+      this.#configurationService.setDefaultsSecretService(
+        new DefaultSecretService(cliConfig.name, ["defaults"], this.#secretsApi),
+      );
     }
     return Promise.resolve({
-      service: this.#configurationService,
+      service: new ConfigurationLocationService(this.#configurationService),
       // this may be empty if configEnabled is false
       commands,
     });
   }
 
+  /**
+   * The {@link DefaultConfigurationService} which owns the configuration data, for trusted wiring and tests.
+   */
+  public get configurationService(): DefaultConfigurationService {
+    return this.#configurationService;
+  }
+
+  public get configLocation(): string | undefined {
+    return this.#configurationService.configLocation;
+  }
+
+  public set configLocation(location: string | undefined) {
+    this.#configurationService.configLocation = location;
+  }
+
+  public get defaultsData(): Map<string, Values | SingleValueType> {
+    return this.#configurationService.defaultsData;
+  }
+
+  public set defaultsData(data: Map<string, Values | SingleValueType>) {
+    this.#configurationService.defaultsData = data;
+  }
+
   public setConfigLocation(configLocation: string) {
-    this.configLocation = configLocation;
+    this.#configurationService.setConfigLocation(configLocation);
   }
 
   /**
@@ -293,19 +334,8 @@ export default class ConfigurationServiceProvider implements ServiceProvider {
       }
     }
 
-    if (result !== undefined && this.#defaultsSecretService) {
-      result = await resolveSecrets<PopulatedValues | PopulatedValueType>(
-        result,
-        async (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}'`,
-            );
-          }
-          return secretValue;
-        },
-      );
+    if (result !== undefined) {
+      result = await this.#configurationService.resolveDefaultSecrets(result, commandKey);
     }
 
     return result;
@@ -322,12 +352,7 @@ export default class ConfigurationServiceProvider implements ServiceProvider {
     scopeType: KeyValueServiceScopeType,
     scopeKey: string,
   ): Map<string, ValueNode> {
-    const keyValueData =
-      scopeType === "command" ? this.#commandKeyValueData : this.#serviceKeyValueData;
-    if (!keyValueData.has(scopeKey)) {
-      keyValueData.set(scopeKey, new Map());
-    }
-    return keyValueData.get(scopeKey)!;
+    return this.#configurationService.getKeyValueData(scopeType, scopeKey);
   }
 
   /**
@@ -337,149 +362,18 @@ export default class ConfigurationServiceProvider implements ServiceProvider {
    *
    * @param isDirty whether any scoped KeyValueService has unwritten changes.
    */
-  public async flushIfDirty(isDirty: boolean): Promise<void> {
-    if (!isDirty) {
-      return;
-    }
-    if (this.configLocation === undefined) {
-      throw new Error("Attempt to write updated config with no configLocation set");
-    }
-    await this.#writeConfig(this.configLocation);
+  public flushIfDirty(isDirty: boolean): Promise<void> {
+    return this.#configurationService.flushIfDirty(isDirty);
   }
 
   public async initService(context: Context): Promise<void> {
     if (!this.configEnabled) {
       return;
     }
-
-    let isDefault = false;
-    if (this.configLocation === undefined) {
-      isDefault = true;
-      // default to `$HOME/.<application_name>.json`
-      const home = process.env["HOME"];
-      if (home) {
-        this.configLocation = path.join(home, `.${context.cliConfig.name.replace(/\W/g, "")}.json`);
-      }
-    }
-    if (this.configLocation === undefined) {
-      return;
-    }
-    let fileInfo: Stats;
-    try {
-      fileInfo = await fs.lstat(this.configLocation);
-    } catch (err) {
-      const error = err as Error;
-      if (isDefault) {
-        logger.debug(
-          "Default config file location: %s does not exist or is not visible - ignoring: %s",
-          this.configLocation,
-          error.message,
-        );
-        return;
-      } else {
-        throw new Error(
-          `Config file location: '${this.configLocation}' doesn't exist or not visible: ${error.message}`,
-        );
-      }
-    }
-    if (fileInfo.isDirectory()) {
-      throw new Error(
-        `Config file location: '${this.configLocation}' is a directory and not a file!`,
-      );
-    }
-
-    await this.#readConfig(this.configLocation);
-  }
-
-  async #readConfig(location: string): Promise<void> {
-    try {
-      logger.debug("Reading config from: %s", location);
-
-      const data = await fs.readFile(location);
-      const config = JSON.parse(data.toString());
-
-      if (config === undefined) {
-        return;
-      }
-      this.defaultsData.clear();
-      this.#commandKeyValueData.clear();
-      this.#serviceKeyValueData.clear();
-      if (config.defaults !== undefined) {
-        const defaults = config.defaults;
-        Object.keys(defaults).forEach((commandName) => {
-          this.defaultsData.set(commandName, defaults[commandName] as Values);
-          logger.debug("Set default argument values for command name: %s", commandName);
-        });
-      }
-      if (config["key-values"] !== undefined) {
-        const keyValues = config["key-values"];
-        if (keyValues.commands !== undefined) {
-          const commandKeyValues = keyValues.commands;
-          Object.keys(commandKeyValues).forEach((commandName) => {
-            this.#commandKeyValueData.set(
-              commandName,
-              new Map(Object.entries(commandKeyValues[commandName])),
-            );
-            logger.debug("Set default argument values for command name: %s", commandName);
-          });
-        }
-        if (keyValues.services !== undefined) {
-          const serviceKeyValues = keyValues.services;
-          Object.keys(serviceKeyValues).forEach((serviceId) => {
-            this.#serviceKeyValueData.set(
-              serviceId,
-              new Map(Object.entries(serviceKeyValues[serviceId])),
-            );
-            logger.debug("Set default argument values for service ID: %s", serviceId);
-          });
-        }
-      }
-    } catch (err) {
-      throw new Error(`Failed to read config at location: '${this.configLocation}': ${err}`);
-    }
-  }
-
-  async #writeConfig(location: string): Promise<void> {
-    logger.debug("Writing config to: %s", location);
-
-    try {
-      await fs.writeFile(location, this.getConfigString());
-    } catch (err) {
-      throw new Error(`Failed to write config at location: '${this.configLocation}': ${err}`);
-    }
+    await this.#configurationService.init(context.cliConfig.name);
   }
 
   public getConfigString(): string {
-    const config: {
-      defaults?: Record<string, Values | SingleValueType>;
-      "key-values"?: {
-        commands?: Record<string, Record<string, ValueNode>>;
-        services?: Record<string, Record<string, ValueNode>>;
-      };
-    } = {};
-
-    if (this.defaultsData.size > 0) {
-      config.defaults = Object.fromEntries(this.defaultsData);
-    }
-    if (this.#commandKeyValueData.size > 0 || this.#serviceKeyValueData.size > 0) {
-      config["key-values"] = {};
-      if (this.#commandKeyValueData.size > 0) {
-        config["key-values"].commands = {};
-        for (const [commandName, keyValueData] of this.#commandKeyValueData.entries()) {
-          if (keyValueData.size > 0) {
-            config["key-values"].commands[commandName] = Object.fromEntries(keyValueData);
-          }
-        }
-      }
-      if (this.#serviceKeyValueData.size > 0) {
-        config["key-values"].services = {};
-        for (const [serviceId, keyValueData] of this.#serviceKeyValueData.entries()) {
-          if (keyValueData.size > 0) {
-            config["key-values"].services[serviceId] = Object.fromEntries(keyValueData);
-          }
-        }
-      }
-    }
-    return JSON.stringify(config, null, 2);
+    return this.#configurationService.getConfigString();
   }
 }