@flowscripter/dynamic-cli-framework 1.1.5 → 1.2.0

package/src/launcher.ts

@@ -1,33 +1,20 @@
 import process from "node:process";
 import path from "node:path";
 import type CLIConfig from "./api/CLIConfig.ts";
+import type BaseCLIFeatureOptions from "./api/BaseCLIFeatureOptions.ts";
 import type SubCommand from "./api/command/SubCommand.ts";
 import DefaultRuntimeCLI from "./cli/DefaultRuntimeCLI.ts";
 import type Command from "./api/command/Command.ts";
 import type RunResult from "./api/RunResult.ts";
 import type { ServiceProvider } from "./api/service/ServiceProvider.ts";
 
-/**
- * Launch a {@link DefaultRuntimeCLI} with a single specified {@link SubCommand} instance.
- *
- * @param command the {@link SubCommand} to add to the CLI.
- * @param description optional description of the CLI.
- * @param name optional name of the CLI. If not provided, `process.execPath` will be used in an attempt to derive the name.
- * @param version optional version of the CLI.
- * @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 serviceProviders optional array of {@link ServiceProvider} instances to add to the CLI.
- */
 export async function launchSingleCommandCLI(
   command: SubCommand,
   description?: string,
   name?: string,
   version?: string,
-  envVarsEnabled = false,
-  configEnabled = false,
-  keyValueServiceEnabled = false,
   serviceProviders?: ReadonlyArray<ServiceProvider>,
+  options?: BaseCLIFeatureOptions,
 ): Promise<RunResult> {
   if (!name) {
     name = path.basename(process.execPath);
@@ -38,20 +25,12 @@ export async function launchSingleCommandCLI(
     version: version || "N/A",
   };
 
-  if (!configEnabled && keyValueServiceEnabled) {
-    throw new Error(
-      "configEnabled must be true if keyValueServiceEnabled is true",
-    );
-  }
-  const validateAllCommands =
-    process.env.DYNAMIC_CLI_FRAMEWORK_VALIDATE_ALL !== undefined;
-  const cli = new DefaultRuntimeCLI(
-    cliConfig,
-    envVarsEnabled,
-    configEnabled,
-    keyValueServiceEnabled,
-    validateAllCommands,
-  );
+  const mergedOptions: BaseCLIFeatureOptions = {
+    ...options,
+    validateAllCommands: (options?.validateAllCommands ?? false) ||
+      process.env.DYNAMIC_CLI_FRAMEWORK_VALIDATE_ALL !== undefined,
+  };
+  const cli = new DefaultRuntimeCLI(cliConfig, mergedOptions);
 
   cli.addCommand(command);
 
@@ -60,27 +39,13 @@ export async function launchSingleCommandCLI(
   return await cli.run();
 }
 
-/**
- * Launch a {@link DefaultRuntimeCLI} with multiple specified {@link Command} instances.
- *
- * @param commands the {@link Command} instances to add to the CLI.
- * @param description optional description of the CLI.
- * @param name optional name of the CLI. If not provided, `process.execPath` will be used in an attempt to derive the name.
- * @param version optional version of the CLI.
- * @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 serviceProviders optional array of {@link ServiceProvider} instances to add to the CLI.
- */
 export async function launchMultiCommandCLI(
   commands: ReadonlyArray<Command>,
   description?: string,
   name?: string,
   version?: string,
-  envVarsEnabled = false,
-  configEnabled = false,
-  keyValueServiceEnabled = false,
   serviceProviders?: ReadonlyArray<ServiceProvider>,
+  options?: BaseCLIFeatureOptions,
 ): Promise<RunResult> {
   if (!name) {
     name = path.basename(process.execPath);
@@ -90,20 +55,13 @@ export async function launchMultiCommandCLI(
     name,
     version: version || "N/A",
   };
-  if (!configEnabled && keyValueServiceEnabled) {
-    throw new Error(
-      "configEnabled must be true if keyValueServiceEnabled is true",
-    );
-  }
-  const validateAllCommands =
-    process.env.DYNAMIC_CLI_FRAMEWORK_VALIDATE_ALL !== undefined;
-  const cli = new DefaultRuntimeCLI(
-    cliConfig,
-    envVarsEnabled,
-    configEnabled,
-    keyValueServiceEnabled,
-    validateAllCommands,
-  );
+
+  const mergedOptions: BaseCLIFeatureOptions = {
+    ...options,
+    validateAllCommands: (options?.validateAllCommands ?? false) ||
+      process.env.DYNAMIC_CLI_FRAMEWORK_VALIDATE_ALL !== undefined,
+  };
+  const cli = new DefaultRuntimeCLI(cliConfig, mergedOptions);
 
   commands.forEach((command) => cli.addCommand(command));
 

package/src/runtime/command/CommandValidator.ts

@@ -36,6 +36,7 @@ function validateValueType(
   value: ArgumentSingleValueType,
   argumentName: string,
   isDefaultValue: boolean,
+  isRangeValue: boolean,
 ): void {
   switch (type) {
     case ArgumentValueTypeName.BOOLEAN:
@@ -51,7 +52,7 @@ function validateValueType(
       if ((typeof value !== "number") || !Number.isFinite(value)) {
         throw new Error(
           `Specified ${
-            isDefaultValue ? "default" : "allowable"
+            isDefaultValue ? "default" : isRangeValue ? "range" : "allowable"
           } value: '${value}' for argument: '${argumentName}' should be a finite number`,
         );
       }
@@ -60,7 +61,7 @@ function validateValueType(
       if ((typeof value !== "number") || !Number.isInteger(value)) {
         throw new Error(
           `Specified ${
-            isDefaultValue ? "default" : "allowable"
+            isDefaultValue ? "default" : isRangeValue ? "range" : "allowable"
           } value: '${value}' for argument: '${argumentName}' should be an integer`,
         );
       }
@@ -97,7 +98,7 @@ function isNameLegal(name: string): boolean {
 function isConfigurationKeyLegal(configurationKey: string): boolean {
   return (configurationKey.length > 0) &&
     isUppercaseAlphaNumericOrUnderscore(configurationKey) &&
-    !configurationKey[0].match(/[0-9]/);
+    !configurationKey[0]!.match(/[0-9]/);
 }
 
 function validateArgument(argument: Argument, name: string): void {
@@ -112,10 +113,73 @@ function validateArgument(argument: Argument, name: string): void {
     );
   }
   if (argument.allowableValues) {
+    if (argument.type === ArgumentValueTypeName.BOOLEAN) {
+      throw new Error(
+        `Illegal type: '${argument.type}' for argument: '${name}' with allowable values specified`,
+      );
+    }
     argument.allowableValues.forEach((value) => {
-      validateValueType(argument.type, value, name, false);
+      validateValueType(argument.type, value, name, false, false);
     });
   }
+  if (argument.isCaseInsensitive !== undefined) {
+    if (
+      (argument.type === ArgumentValueTypeName.BOOLEAN) &&
+      (argument.isCaseInsensitive === false)
+    ) {
+      throw new Error(
+        `Illegal type: '${argument.type}' for argument: '${name}' must always be case insensitive`,
+      );
+    } else if (argument.type !== ArgumentValueTypeName.STRING) {
+      throw new Error(
+        `Illegal type: '${argument.type}' for argument: '${name}' with case insensitive specified`,
+      );
+    }
+  }
+  if (argument.minValueInclusive !== undefined) {
+    if (
+      (argument.type !== ArgumentValueTypeName.NUMBER) &&
+      (argument.type !== ArgumentValueTypeName.INTEGER)
+    ) {
+      throw new Error(
+        `Illegal type: '${argument.type}' for argument: '${name}' with min value specified`,
+      );
+    }
+    if (argument.allowableValues) {
+      throw new Error(
+        `Illegal combination of allowable values and min value for argument: '${name}'`,
+      );
+    }
+    validateValueType(
+      argument.type,
+      argument.minValueInclusive,
+      name,
+      false,
+      true,
+    );
+  }
+  if (argument.maxValueInclusive !== undefined) {
+    if (
+      (argument.type !== ArgumentValueTypeName.NUMBER) &&
+      (argument.type !== ArgumentValueTypeName.INTEGER)
+    ) {
+      throw new Error(
+        `Illegal type: '${argument.type}' for argument: '${name}' with max value specified`,
+      );
+    }
+    if (argument.allowableValues) {
+      throw new Error(
+        `Illegal combination of allowable values and max value for argument: '${name}'`,
+      );
+    }
+    validateValueType(
+      argument.type,
+      argument.maxValueInclusive,
+      name,
+      false,
+      true,
+    );
+  }
 }
 
 function validateSubCommandArgument(
@@ -304,7 +368,7 @@ export default class CommandValidator {
     }
     if (subCommand.positionals) {
       for (let i = 0; i < subCommand.positionals.length; i += 1) {
-        const positional = subCommand.positionals[i];
+        const positional = subCommand.positionals[i]!;
         validateSubCommandArgument(positional);
         if (argumentNames.includes(positional.name)) {
           throw new Error(
@@ -332,7 +396,7 @@ export default class CommandValidator {
     command: Command,
     argumentAncestry: Array<SubCommandArgument>,
   ) {
-    const argument = argumentAncestry[argumentAncestry.length - 1];
+    const argument = argumentAncestry[argumentAncestry.length - 1]!;
     if (command.enableConfiguration === true) {
       if (
         (argument.configurationKey !== undefined) &&

package/src/runtime/runner.ts

@@ -12,6 +12,7 @@ import type {
 import getLogger from "../util/logger.ts";
 import {
   printCommandExecutionError,
+  printNoCommandRecognisedError,
   printNoCommandSpecifiedError,
   printParseResultError,
   printUnusedArgsWarning,
@@ -32,9 +33,35 @@ import type GroupCommand from "../api/command/GroupCommand.ts";
 import type SubCommand from "../api/command/SubCommand.ts";
 import type GlobalCommand from "../api/command/GlobalCommand.ts";
 import type Command from "../api/command/Command.ts";
+import type ArgumentPrompterService from "../api/service/core/ArgumentPrompterService.ts";
+import { ARGUMENT_PROMPTER_SERVICE_ID } from "../api/service/core/ArgumentPrompterService.ts";
 
 const logger = getLogger("runner");
 
+async function attemptPromptForMissingArguments(
+  parseResult: ParseResult,
+  context: Context,
+): Promise<ParseResult | undefined> {
+  if (!context.doesServiceExist(ARGUMENT_PROMPTER_SERVICE_ID)) {
+    return undefined;
+  }
+  const service = context.getServiceById(
+    ARGUMENT_PROMPTER_SERVICE_ID,
+  ) as ArgumentPrompterService;
+  try {
+    const updated = await service.promptForMissingArguments(parseResult);
+    if (updated.invalidArguments.length === 0) {
+      return updated;
+    }
+  } catch (error) {
+    if ((error as Error).message === "Interrupted") {
+      throw error;
+    }
+    return undefined;
+  }
+  return undefined;
+}
+
 /**
  * Execute the {@link Command} with arguments contained in the provided {@link ParseResult}.
  *
@@ -55,13 +82,19 @@ async function executeParsedCommand(
         "Executing group command with name: %s",
         parseResult!.groupCommand!.name,
       );
-      if (configurationServiceProvider?.keyValueServiceEnabled) {
+      if (
+        configurationServiceProvider?.keyValueServiceEnabled ||
+        configurationServiceProvider?.secretServiceEnabled
+      ) {
         configurationServiceProvider.setCommandKeyValueScope(
           parseResult!.groupCommand!.name,
         );
       }
       await parseResult.groupCommand.execute(context);
-      if (configurationServiceProvider?.keyValueServiceEnabled) {
+      if (
+        configurationServiceProvider?.keyValueServiceEnabled ||
+        configurationServiceProvider?.secretServiceEnabled
+      ) {
         await configurationServiceProvider.clearKeyValueScope();
       }
     }
@@ -72,7 +105,10 @@ async function executeParsedCommand(
       parseResult!.populatedArgumentValues,
     );
 
-    if (configurationServiceProvider?.keyValueServiceEnabled) {
+    if (
+      configurationServiceProvider?.keyValueServiceEnabled ||
+      configurationServiceProvider?.secretServiceEnabled
+    ) {
       configurationServiceProvider.setCommandKeyValueScope(
         parseResult.command.name,
       );
@@ -88,10 +124,16 @@ async function executeParsedCommand(
         parseResult.populatedArgumentValues as ArgumentSingleValueType,
       );
     }
-    if (configurationServiceProvider?.keyValueServiceEnabled) {
+    if (
+      configurationServiceProvider?.keyValueServiceEnabled ||
+      configurationServiceProvider?.secretServiceEnabled
+    ) {
       await configurationServiceProvider.clearKeyValueScope();
     }
   } catch (err) {
+    if ((err as Error).message === "Interrupted") {
+      throw err;
+    }
     await printCommandExecutionError(
       context,
       parseResult,
@@ -154,7 +196,7 @@ async function findAndExecuteGlobalModifierCommands(
     ) {
       // parse and fast fail on error
       const defaultArgumentValues = configurationServiceProvider
-        ? configurationServiceProvider
+        ? await configurationServiceProvider
           .getDefaultArgumentValues(
             context.cliConfig,
             globalModifierCommandClause.command,
@@ -194,7 +236,7 @@ async function findAndExecuteGlobalModifierCommands(
   for (const globalModifierCommand of remainingGlobalModifierCommands) {
     // if there is a config entry run this by default even though no arguments were provided on the command line
     const defaultArgumentValues = configurationServiceProvider
-      ? configurationServiceProvider
+      ? await configurationServiceProvider
         .getDefaultArgumentValues(context.cliConfig, globalModifierCommand)
       : undefined;
 
@@ -273,7 +315,7 @@ async function findAndExecuteNonModifierCommand(
 
   if (scanResult.nonModifierCommandClause) {
     const defaultArgumentValues = configurationServiceProvider
-      ? configurationServiceProvider
+      ? await configurationServiceProvider
         .getDefaultArgumentValues(
           context.cliConfig,
           scanResult.nonModifierCommandClause.command,
@@ -293,12 +335,20 @@ async function findAndExecuteNonModifierCommand(
     }
 
     if (parseResult.invalidArguments.length > 0) {
-      await printParseResultError(context, parseResult);
-      return {
-        runState: RunState.PARSE_ERROR,
-        command: parseResult.command,
-        invalidArguments: parseResult.invalidArguments,
-      };
+      const prompted = await attemptPromptForMissingArguments(
+        parseResult,
+        context,
+      );
+      if (prompted) {
+        parseResult = prompted;
+      } else {
+        await printParseResultError(context, parseResult);
+        return {
+          runState: RunState.PARSE_ERROR,
+          command: parseResult.command,
+          invalidArguments: parseResult.invalidArguments,
+        };
+      }
     }
 
     // add any unused args back to the list of still unused args
@@ -310,7 +360,7 @@ async function findAndExecuteNonModifierCommand(
     for (const nonModifierCommand of nonModifierCommandsByName.values()) {
       // if there is a config entry run this by default even though no arguments were provided on the command line
       const defaultArgumentValues = configurationServiceProvider
-        ? configurationServiceProvider
+        ? await configurationServiceProvider
           .getDefaultArgumentValues(context.cliConfig, nonModifierCommand)
         : undefined;
 
@@ -328,12 +378,20 @@ async function findAndExecuteNonModifierCommand(
         }
 
         if (parseResult.invalidArguments.length > 0) {
-          await printParseResultError(context, parseResult);
-          return {
-            runState: RunState.PARSE_ERROR,
-            command: parseResult.command,
-            invalidArguments: parseResult.invalidArguments,
-          };
+          const prompted = await attemptPromptForMissingArguments(
+            parseResult,
+            context,
+          );
+          if (prompted) {
+            parseResult = prompted;
+          } else {
+            await printParseResultError(context, parseResult);
+            return {
+              runState: RunState.PARSE_ERROR,
+              command: parseResult.command,
+              invalidArguments: parseResult.invalidArguments,
+            };
+          }
         }
 
         break;
@@ -375,7 +433,7 @@ async function findAndExecuteDefaultNonModifierCommand(
   context: Context,
 ): Promise<RunResult | undefined> {
   const defaultArgumentValues = configurationServiceProvider
-    ? configurationServiceProvider
+    ? await configurationServiceProvider
       .getDefaultArgumentValues(context.cliConfig, defaultNonModifierCommand)
     : undefined;
   const isGlobal = isGlobalCommand(defaultNonModifierCommand);
@@ -447,14 +505,23 @@ async function findAndExecuteDefaultNonModifierCommand(
     }
   }
 
-  // if there were invalid arguments, treat this as the error
+  // if there were invalid arguments, attempt prompting before treating as error
   if (lastErroneousParseResult) {
-    await printParseResultError(context, lastErroneousParseResult, true);
-    return {
-      runState: RunState.PARSE_ERROR,
-      command: defaultNonModifierCommand,
-      invalidArguments: lastErroneousParseResult.invalidArguments,
-    };
+    const prompted = await attemptPromptForMissingArguments(
+      lastErroneousParseResult,
+      context,
+    );
+    if (prompted) {
+      parseResult = prompted;
+      lastErroneousParseResult = undefined;
+    } else {
+      await printParseResultError(context, lastErroneousParseResult, true);
+      return {
+        runState: RunState.PARSE_ERROR,
+        command: defaultNonModifierCommand,
+        invalidArguments: lastErroneousParseResult.invalidArguments,
+      };
+    }
   }
 
   // give up if still nothing found
@@ -603,14 +670,20 @@ export async function run(
 
     logger.debug("Initialising service with ID: %s", serviceProvider.serviceId);
 
-    if (configurationServiceProvider?.keyValueServiceEnabled) {
+    if (
+      configurationServiceProvider?.keyValueServiceEnabled ||
+      configurationServiceProvider?.secretServiceEnabled
+    ) {
       configurationServiceProvider.setServiceKeyValueScope(
         serviceProvider.serviceId,
       );
     }
 
     await serviceProvider.initService(context);
-    if (configurationServiceProvider?.keyValueServiceEnabled) {
+    if (
+      configurationServiceProvider?.keyValueServiceEnabled ||
+      configurationServiceProvider?.secretServiceEnabled
+    ) {
       await configurationServiceProvider.clearKeyValueScope();
     }
   }
@@ -690,7 +763,15 @@ export async function run(
   }
 
   // give up if we haven't successfully parsed a non-modifier Command by now
-  await printNoCommandSpecifiedError(context);
+  if (availableArgs.length > 0) {
+    await printNoCommandRecognisedError(
+      context,
+      commandRegistry,
+      availableArgs.flat(),
+    );
+  } else {
+    await printNoCommandSpecifiedError(context);
+  }
   return {
     runState: RunState.NO_COMMAND,
   };

package/src/runtime/scanner.ts

@@ -67,15 +67,15 @@ function normaliseFirstArgumentIfRequired(
   // --<global_[modifier_]command_name>=<value>
   // -<global_[modifier_]command_short_alias>
   // -<global_[modifier_]command_short_alias>=<value>
-  if ((firstArg.length < 2) || (firstArg.charAt(0) !== "-")) {
+  if ((firstArg!.length < 2) || (firstArg!.charAt(0) !== "-")) {
     return args;
   }
 
   // looking for:
   // --<global_[modifier_]command_name>
   // --<global_[modifier_]command_name>=<value>
-  if ((firstArg.length > 2) && (firstArg.charAt(1) === "-")) {
-    let potentialGlobalCommandName = firstArg.slice(2);
+  if ((firstArg!.length > 2) && (firstArg!.charAt(1) === "-")) {
+    let potentialGlobalCommandName = firstArg!.slice(2);
 
     // looking for:
     // <global_command_name>=<value>
@@ -84,7 +84,7 @@ function normaliseFirstArgumentIfRequired(
     if (potentialGlobalCommandName.includes("=")) {
       [potentialGlobalCommandName, nextArg] = potentialGlobalCommandName.split(
         /=(.*)/,
-      );
+      ) as [string, string | undefined];
     }
 
     if (!globalCommandsByName.has(potentialGlobalCommandName)) {
@@ -105,14 +105,17 @@ function normaliseFirstArgumentIfRequired(
   // -<global_[modifier_]command_short_alias>
   // -<global_[modifier_]command_short_alias>=<value>
   // (by now we know the arg starts with -<char>)
-  let potentialGlobalCommandShortAlias = firstArg.slice(1);
+  let potentialGlobalCommandShortAlias = firstArg!.slice(1);
 
   // looking for:
   // <global_[modifier_]command_short_alias>=<value>
   let nextArg: string | undefined;
   if (potentialGlobalCommandShortAlias.includes("=")) {
     [potentialGlobalCommandShortAlias, nextArg] =
-      potentialGlobalCommandShortAlias.split(/=(.*)/);
+      potentialGlobalCommandShortAlias.split(/=(.*)/) as [
+        string,
+        string | undefined,
+      ];
   }
 
   if (!globalCommandsByShortAlias) {
@@ -169,8 +172,8 @@ function scanForNextCommandClause(
 
     // looking for:
     // <global_[modifier_]command_name>
-    if (currentArg.startsWith("--")) {
-      const potentialCommandName = currentArg.slice(2);
+    if (currentArg!.startsWith("--")) {
+      const potentialCommandName = currentArg!.slice(2);
 
       // check for Global[Modifier]Command name
       const command = commandsByName.get(potentialCommandName);
@@ -188,8 +191,8 @@ function scanForNextCommandClause(
         };
       }
     }
-    if (!includeSubCommands || (currentArg[0] === "-")) {
-      unusedArgs.push(currentArg);
+    if (!includeSubCommands || (currentArg![0] === "-")) {
+      unusedArgs.push(currentArg!);
       continue;
     }
 
@@ -202,11 +205,11 @@ function scanForNextCommandClause(
       let potentialMemberSubCommandName: string | undefined;
       let potentialMemberCommandNameArgumentUsed = false;
 
-      if (potentialGroupCommandName.includes(":")) {
+      if (potentialGroupCommandName!.includes(":")) {
         // looking for:
         // <group_command_name>:<member_sub_command_name>
         [potentialGroupCommandName, potentialMemberSubCommandName] =
-          potentialGroupCommandName.split(":");
+          potentialGroupCommandName!.split(":") as [string, string | undefined];
       } else if (pendingArgs.length > 0) {
         // looking for:
         // <group_command_name> <member_sub_command_name>
@@ -250,9 +253,9 @@ function scanForNextCommandClause(
     //
     // if we find it is a group command we skip it as we didn't find a member command
     // following it the logic above
-    const command = commandsByName.get(currentArg);
+    const command = commandsByName.get(currentArg!);
     if (command && !isGroupCommand(command)) {
-      logger.debug("Found sub-command name: %s", currentArg);
+      logger.debug("Found sub-command name: %s", currentArg!);
       return {
         commandClause: {
           command,
@@ -263,7 +266,7 @@ function scanForNextCommandClause(
     }
 
     // if we got here we haven't found a command so add the current arg to unused args
-    unusedArgs.push(currentArg);
+    unusedArgs.push(currentArg!);
   }
   // if we got here we haven't found a command and we have processed all provided args
   return {