@flowscripter/dynamic-cli-framework 9.1.3 → 10.1.0

package/src/service/configuration/ConfigurationServiceProvider.ts

@@ -13,6 +13,7 @@ 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 DumpConfigCommand from "./command/DumpConfigCommand.ts";
 import {
   CONFIGURATION_SERVICE_ID,
@@ -77,7 +78,8 @@ class ConfigurationServiceImpl implements ConfigurationService {
  *
  * A JSON file 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}
- * and the contained values are treated as command {@link Values}. As an example:
+ * (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:
  *
  * ```
  * {
@@ -94,6 +96,9 @@ class ConfigurationServiceImpl implements ConfigurationService {
  *         "command2": {
  *             "arg4": true
  *         },
+ *         "group1:member1": {
+ *             "arg5": "bar"
+ *         },
  *         "globalCommand": "globalArgumentValue"
  *     },
  *     "key-values": {
@@ -124,13 +129,15 @@ class ConfigurationServiceImpl implements ConfigurationService {
  * Argument configuration keys are concatenated with a `_` separator.
  * Any arguments which support array values must by suffixed with `_` and an explicit array index.
  * If the root argument in the path does not use a custom {@link Argument.configurationKey} then the key path
- * is additionally suffixed with the {@link CLIConfig.name} and the {@link Command.name} with `_` separators.
+ * is additionally prefixed with the {@link CLIConfig.name}, the {@link GroupCommand.name} (if the command is a group
+ * member) and the {@link Command.name} with `_` separators.
  * This is best explained with examples...
  *
  * No custom configuration key examples:
  *
  * * executable: `MyCLI`, command: `globalCommand1`, global command argument => environment variable: `MYCLI_GLOBALCOMMAND1`
  * * executable: `MyCLI`, command: `command1`, simple root argument: `arg1` => environment variable: `MYCLI_COMMAND1_ARG1`
+ * * executable: `MyCLI`, group: `group1`, member command: `member1`, simple root argument: `arg1` => environment variable: `MYCLI_GROUP1_MEMBER1_ARG1`
  * * executable: `MyCLI`, command: `command1`, array root argument, 1st element: `arg2[0]` => environment variable: `MYCLI_COMMAND1_ARG2_0`
  * * executable: `MyCLI`, command: `command1`, argument is a digit so it is by default suffixed with `_`: `3` => environment variable: `MYCLI_COMMAND1__3`
  * * executable: `MyCLI`, command: `command1`, nested sub-argument: `arg1.arg2` => environment variable: `MYCLI_COMMAND1_ARG1_ARG2`
@@ -238,17 +245,22 @@ export default class ConfigurationServiceProvider implements ServiceProvider {
    *
    * @param cliConfig the {@link CLIConfig} to use for retrieving configuration keys.
    * @param command the {@link Command} instance to retrieve default argument values for.
+   * @param groupCommand the {@link GroupCommand} if the command is a group member. The configuration file key
+   * is then `<group name>:<command name>` and the env var names include the group name.
    */
   public async getDefaultArgumentValues(
     cliConfig: CLIConfig,
     command: Command,
+    groupCommand?: GroupCommand,
   ): Promise<PopulatedValues | PopulatedValueType | undefined> {
     if (!this.configEnabled) {
       logger.debug("configuration of default values is not enabled");
       return undefined;
     }
 
-    logger.debug("getting default argument values for command: %s", command.name);
+    const commandKey = groupCommand ? `${groupCommand.name}:${command.name}` : command.name;
+
+    logger.debug("getting default argument values for command: %s", commandKey);
 
     if (command.enableConfiguration === undefined || command.enableConfiguration !== true) {
       logger.debug("enableConfiguration for command: %s is not true", command.name);
@@ -258,16 +270,16 @@ export default class ConfigurationServiceProvider implements ServiceProvider {
     let result: PopulatedValues | PopulatedValueType | undefined;
 
     if (isGlobalModifierCommand(command) || isGlobalCommand(command)) {
-      const configuredValue = this.defaultsData.get(command.name) as SingleValueType;
+      const configuredValue = this.defaultsData.get(commandKey) as SingleValueType;
       const envVarValue = this.envVarsEnabled
         ? getGlobalCommandValueFromEnvVars(cliConfig, command)
         : undefined;
       // default to environment variable value
       result = envVarValue !== undefined ? envVarValue : configuredValue;
     } else if (isSubCommand(command)) {
-      const configuredValues = this.defaultsData.get(command.name) as Values;
+      const configuredValues = this.defaultsData.get(commandKey) as Values;
       const envVarValues = this.envVarsEnabled
-        ? getSubCommandValuesFromEnvVars(cliConfig, command)
+        ? getSubCommandValuesFromEnvVars(cliConfig, command, groupCommand)
         : undefined;
       if (envVarValues === undefined) {
         result = configuredValues;

package/src/util/configHelper.ts

@@ -1,3 +1,4 @@
+import type { GroupCommand } from "@flowscripter/dynamic-cli-framework-api";
 import type { Command } from "@flowscripter/dynamic-cli-framework-api";
 import type { CLIConfig } from "@flowscripter/dynamic-cli-framework-api";
 import type { Option } from "@flowscripter/dynamic-cli-framework-api";
@@ -26,11 +27,14 @@ function getKeySegment(segment: string, isCustom = false, isArray = false) {
  * @param command the {@link Command} to use for determining the default configuration key.
  * @param argumentAncestry a list of {@link SubCommandArgument} instances from the root command arguments to a leaf argument.
  * Apart from {@link ComplexOption} instances this will always only have a single entry.
+ * @param groupCommand the {@link GroupCommand} if the command is a member of a group, in which case the group name
+ * is an additional key segment.
  */
 export function getSubCommandArgumentConfigurationKey(
   cliConfig: CLIConfig,
   command: Command,
   argumentAncestry: Array<SubCommandArgument>,
+  groupCommand?: GroupCommand,
 ): string | undefined {
   if (command.enableConfiguration === undefined || command.enableConfiguration !== true) {
     return undefined;
@@ -43,6 +47,9 @@ export function getSubCommandArgumentConfigurationKey(
   const firstArgument = argumentAncestry[0]!;
   if (firstArgument.configurationKey === undefined) {
     keySegments.push(getKeySegment(cliConfig.name));
+    if (groupCommand) {
+      keySegments.push(getKeySegment(groupCommand.name));
+    }
     keySegments.push(getKeySegment(command.name));
   }
 

package/src/util/envVarHelper.ts

@@ -14,6 +14,7 @@ import { MAXIMUM_ARGUMENT_ARRAY_SIZE } from "@flowscripter/dynamic-cli-framework
 import type { Option } from "@flowscripter/dynamic-cli-framework-api";
 import type { GlobalCommandArgument } from "@flowscripter/dynamic-cli-framework-api";
 import type { GlobalCommand } from "@flowscripter/dynamic-cli-framework-api";
+import type { GroupCommand } from "@flowscripter/dynamic-cli-framework-api";
 import type { SubCommand } from "@flowscripter/dynamic-cli-framework-api";
 import type { ComplexOption } from "@flowscripter/dynamic-cli-framework-api";
 
@@ -29,11 +30,13 @@ function getSubCommandArgumentKeyPrefix(
   cliConfig: CLIConfig,
   command: Command,
   subCommandArgument: SubCommandArgument,
+  groupCommand?: GroupCommand,
 ) {
   if (subCommandArgument.configurationKey) {
     return subCommandArgument.configurationKey;
   }
-  return `${getKeySegment(cliConfig.name)}_${getKeySegment(command.name)}_${getKeySegment(
+  const groupSegment = groupCommand ? `${getKeySegment(groupCommand.name)}_` : "";
+  return `${getKeySegment(cliConfig.name)}_${groupSegment}${getKeySegment(command.name)}_${getKeySegment(
     subCommandArgument.name,
   )}`;
 }
@@ -214,16 +217,24 @@ function getOptionValuesFromEnvVars(
  * @param cliConfig the {@link CLIConfig} to use for determining the default configuration key.
  * @param command the {@link SubCommand} to use for determining the default configuration key and containing
  * {@link Positional} and {@link Option} instances to populate values for.
+ * @param groupCommand the {@link GroupCommand} if the command is a group member, in which case the group name
+ * is an additional env var name segment.
  */
 export function getSubCommandValuesFromEnvVars(
   cliConfig: CLIConfig,
   command: SubCommand,
+  groupCommand?: GroupCommand,
 ): PopulatedValues | undefined {
   const envVarValues = Object.create(null) as PopulatedValues;
   if (command.options) {
     for (const option of command.options) {
       const potentialEnvVarNames = Object.keys(process.env);
-      const optionPrefix = getSubCommandArgumentKeyPrefix(cliConfig, command, option as Option);
+      const optionPrefix = getSubCommandArgumentKeyPrefix(
+        cliConfig,
+        command,
+        option as Option,
+        groupCommand,
+      );
       getOptionValuesFromEnvVars(
         envVarValues,
         potentialEnvVarNames,
@@ -244,7 +255,12 @@ export function getSubCommandValuesFromEnvVars(
           `Unsafe key name in use: ${positional.name}, CodeQL Rule ID: js/prototype-polluting-assignment`,
         );
       }
-      let envVarNamePrefix = getSubCommandArgumentKeyPrefix(cliConfig, command, positional);
+      let envVarNamePrefix = getSubCommandArgumentKeyPrefix(
+        cliConfig,
+        command,
+        positional,
+        groupCommand,
+      );
 
       if (positional.isVarargMultiple) {
         envVarNamePrefix = `${envVarNamePrefix}_`;

package/src/util/helpHelper.ts

@@ -312,6 +312,7 @@ function getOptionHelpEntry(
   option: Option | ComplexOption,
   subEntryIndent = 0,
   optionAncestry: Array<Option | ComplexOption> = [],
+  groupCommand?: GroupCommand,
 ): HelpEntry {
   let subEntries: Array<HelpEntry> | undefined;
   let optionCharacters = "--";
@@ -328,10 +329,15 @@ function getOptionHelpEntry(
     subEntries = [];
     option.properties.forEach((property) => {
       subEntries!.push(
-        getOptionHelpEntry(cliConfig, includeEnvVars, command, property, newSubEntryIndent, [
-          ...optionAncestry,
-          option,
-        ]),
+        getOptionHelpEntry(
+          cliConfig,
+          includeEnvVars,
+          command,
+          property,
+          newSubEntryIndent,
+          [...optionAncestry, option],
+          groupCommand,
+        ),
       );
     });
   } else {
@@ -384,10 +390,12 @@ function getOptionHelpEntry(
   }
 
   if (includeEnvVars && option.type !== ComplexValueTypeName.COMPLEX) {
-    const configurationKey = getSubCommandArgumentConfigurationKey(cliConfig, command, [
-      ...(optionAncestry as Array<SubCommandArgument>),
-      option as unknown as SubCommandArgument,
-    ]);
+    const configurationKey = getSubCommandArgumentConfigurationKey(
+      cliConfig,
+      command,
+      [...(optionAncestry as Array<SubCommandArgument>), option as unknown as SubCommandArgument],
+      groupCommand,
+    );
     if (configurationKey !== undefined) {
       notesItems.push(`env var: ${configurationKey}`);
     }
@@ -418,6 +426,7 @@ function getPositionalHelpEntry(
   includeEnvVars: boolean,
   command: Command,
   positional: Positional,
+  groupCommand?: GroupCommand,
 ): HelpEntry {
   const notesItems: Array<string> = [];
   if (positional.allowableValues !== undefined && positional.allowableValues.length > 0) {
@@ -458,9 +467,12 @@ function getPositionalHelpEntry(
   }
 
   if (includeEnvVars) {
-    const configurationKey = getSubCommandArgumentConfigurationKey(cliConfig, command, [
-      positional,
-    ]);
+    const configurationKey = getSubCommandArgumentConfigurationKey(
+      cliConfig,
+      command,
+      [positional],
+      groupCommand,
+    );
     if (configurationKey !== undefined) {
       notesItems.push(`env var: ${configurationKey}`);
     }
@@ -486,6 +498,7 @@ export function getCommandArgsHelpSections(
   includeEnvVars: boolean,
   subCommand: SubCommand,
   isSingleCommandApp: boolean,
+  groupCommand?: GroupCommand,
 ): Array<HelpSection> {
   const helpSections: Array<HelpSection> = [];
   if (subCommand.options.length > 0 || subCommand.positionals.length > 0) {
@@ -495,12 +508,20 @@ export function getCommandArgsHelpSections(
     };
     subCommand.options.forEach((option) => {
       argumentsSection.helpEntries.push(
-        getOptionHelpEntry(cliConfig, includeEnvVars, subCommand, option as Option),
+        getOptionHelpEntry(
+          cliConfig,
+          includeEnvVars,
+          subCommand,
+          option as Option,
+          0,
+          [],
+          groupCommand,
+        ),
       );
     });
     subCommand.positionals.forEach((positional) => {
       argumentsSection.helpEntries.push(
-        getPositionalHelpEntry(cliConfig, includeEnvVars, subCommand, positional),
+        getPositionalHelpEntry(cliConfig, includeEnvVars, subCommand, positional, groupCommand),
       );
     });
     helpSections.push(argumentsSection);

package/src/util/runnerHelper.ts

@@ -1,5 +1,6 @@
 import type { PrinterService } from "@flowscripter/dynamic-cli-framework-api";
 import { Icon, PRINTER_SERVICE_ID } from "@flowscripter/dynamic-cli-framework-api";
+import type { SecretAwareParseResult } from "../runtime/parser.ts";
 import type { ParseResult } from "../runtime/parser.ts";
 import { isGlobalCommand, isGlobalModifierCommand } from "../runtime/command/CommandTypeGuards.ts";
 import type { Context } from "@flowscripter/dynamic-cli-framework-api";
@@ -122,3 +123,20 @@ export async function printUnusedArgsWarning(
     await printerService.warn(`Unused args: ${overallUnusedArgs.join(" ")}\n\n`, Icon.ALERT);
   }
 }
+
+export async function printSecretArgsWarning(
+  context: Context,
+  parseResult: SecretAwareParseResult,
+) {
+  const secretArgumentNames = parseResult.secretArgumentNames;
+  if (!secretArgumentNames || secretArgumentNames.length === 0) {
+    return;
+  }
+  const printerService = context.getServiceById(PRINTER_SERVICE_ID) as PrinterService;
+  await printerService.warn(
+    `SECRET value passed as a plain argument: ${secretArgumentNames.join(", ")}. ` +
+      "This is not recommended as it may be exposed via shell history and process listings. " +
+      "Use an environment variable, a prompt or a configuration file default instead.\n\n",
+    Icon.ALERT,
+  );
+}

package/src/util/secretRedaction.ts

@@ -0,0 +1,81 @@
+import {
+  ValueTypeName,
+  type ComplexOption,
+  type GlobalCommand,
+  type Option,
+  type PopulatedSingleValueType,
+  type PopulatedValues,
+  type PopulatedValueType,
+  type SubCommand,
+} from "@flowscripter/dynamic-cli-framework-api";
+import { isComplexOption } from "../runtime/argument/ArgumentTypeGuards.ts";
+
+export const REDACTED = "***";
+
+type NamedArgument = { readonly name: string; readonly type?: unknown };
+
+type RedactableValue =
+  | PopulatedValueType
+  | PopulatedValues
+  | Array<PopulatedValues | undefined>
+  | undefined;
+
+function redactValue(
+  definition: NamedArgument | ComplexOption,
+  value: RedactableValue | PopulatedValues,
+): unknown {
+  if (value === undefined || value === null) {
+    return value;
+  }
+  if (isComplexOption(definition as ComplexOption)) {
+    const properties = (definition as ComplexOption).properties;
+    if (Array.isArray(value)) {
+      return value.map((v) => redactValue(definition, v));
+    }
+    return redactDefinedValues(properties, [], value as PopulatedValues);
+  }
+  if (definition.type === ValueTypeName.SECRET) {
+    return Array.isArray(value) ? value.map(() => REDACTED) : REDACTED;
+  }
+  return value;
+}
+
+function redactDefinedValues(
+  options: ReadonlyArray<Option | ComplexOption>,
+  positionals: ReadonlyArray<NamedArgument>,
+  values: PopulatedValues,
+): PopulatedValues {
+  const redacted: Record<string, unknown> = {};
+  for (const [name, value] of Object.entries(values)) {
+    const definition =
+      options.find((o) => o.name === name) ?? positionals.find((p) => p.name === name);
+    redacted[name] = definition ? redactValue(definition, value) : value;
+  }
+  return redacted as PopulatedValues;
+}
+
+/**
+ * Copy of the provided values suitable for logging, with the values of any SECRET options or positionals replaced.
+ */
+export function redactSubCommandValues<T extends PopulatedValues | undefined>(
+  subCommand: SubCommand,
+  values: T,
+): T {
+  if (values === undefined) {
+    return values;
+  }
+  return redactDefinedValues(subCommand.options, subCommand.positionals, values) as T;
+}
+
+/**
+ * Copy of the provided value suitable for logging, with the value replaced if the global command argument is a SECRET.
+ */
+export function redactGlobalCommandValue(
+  globalCommand: GlobalCommand,
+  value: PopulatedSingleValueType,
+): PopulatedSingleValueType {
+  if (value !== undefined && globalCommand.argument?.type === ValueTypeName.SECRET) {
+    return REDACTED;
+  }
+  return value;
+}