@flowscripter/dynamic-cli-framework 11.0.0 → 12.0.0

package/src/runtime/command/CommandValidator.ts

@@ -4,7 +4,7 @@ import type { GlobalCommand } from "@flowscripter/dynamic-cli-framework-api";
 import type { Argument } 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 { SingleValueType } from "@flowscripter/dynamic-cli-framework-api";
+import type { PopulatedValues, SingleValueType } from "@flowscripter/dynamic-cli-framework-api";
 import { ValueTypeName, ComplexValueTypeName } from "@flowscripter/dynamic-cli-framework-api";
 import type { Option } from "@flowscripter/dynamic-cli-framework-api";
 import type { ComplexOption } from "@flowscripter/dynamic-cli-framework-api";
@@ -13,6 +13,8 @@ import {
   getInvalidArgumentString,
   validateGlobalCommandArgumentValue,
   validateOptionValue,
+  runCustomValidation,
+  type DeferredCustomValidation,
 } from "../values/argumentValueValidation.ts";
 import getLogger from "../../util/logger.ts";
 import type { CLIConfig } from "@flowscripter/dynamic-cli-framework-api";
@@ -219,7 +221,16 @@ export default class CommandValidator {
       validateArgument(argument, globalCommand.name);
       if (argument.defaultValue) {
         const invalidArguments: Array<InvalidArgument> = [];
-        validateGlobalCommandArgumentValue(globalCommand, argument.defaultValue, invalidArguments);
+        const deferred: Array<DeferredCustomValidation> = [];
+        validateGlobalCommandArgumentValue(
+          globalCommand,
+          argument.defaultValue,
+          invalidArguments,
+          deferred,
+        );
+        if (invalidArguments.length === 0) {
+          runCustomValidation(deferred, globalCommand, argument.defaultValue, invalidArguments);
+        }
         if (invalidArguments.length > 0) {
           throw new Error(
             `Illegal default value for global command: '${globalCommand.name}' => ${invalidArguments
@@ -440,12 +451,13 @@ export default class CommandValidator {
         option as unknown as SubCommandArgument,
       ]);
     } else {
-      this.#validateOption(option, currentOptionPaths, allOptionPaths);
+      this.#validateOption(subCommand, option, currentOptionPaths, allOptionPaths);
       this.#validateSubCommandArgumentConfigurationKey(subCommand, [...argumentAncestry, option]);
     }
   }
 
   #validateOption(
+    subCommand: SubCommand,
     option: Option,
     currentOptionPaths: Array<string>,
     allOptionPaths: Array<string>,
@@ -460,7 +472,16 @@ export default class CommandValidator {
     }
     if (option.defaultValue) {
       const invalidArguments: Array<InvalidArgument> = [];
-      validateOptionValue(option, option.defaultValue, invalidArguments);
+      const deferred: Array<DeferredCustomValidation> = [];
+      validateOptionValue(option, option.defaultValue, invalidArguments, deferred);
+      if (invalidArguments.length === 0) {
+        runCustomValidation(
+          deferred,
+          subCommand,
+          { [option.name]: option.defaultValue } as PopulatedValues,
+          invalidArguments,
+        );
+      }
       if (invalidArguments.length > 0) {
         throw new Error(
           `Illegal default value for option: '${option.name}' => ${invalidArguments
@@ -515,7 +536,16 @@ export default class CommandValidator {
     }
     if (complexOption.defaultValue) {
       const invalidArguments: Array<InvalidArgument> = [];
-      validateOptionValue(complexOption, complexOption.defaultValue, invalidArguments);
+      const deferred: Array<DeferredCustomValidation> = [];
+      validateOptionValue(complexOption, complexOption.defaultValue, invalidArguments, deferred);
+      if (invalidArguments.length === 0) {
+        runCustomValidation(
+          deferred,
+          subCommand,
+          { [complexOption.name]: complexOption.defaultValue } as PopulatedValues,
+          invalidArguments,
+        );
+      }
       if (invalidArguments.length > 0) {
         throw new Error(
           `Illegal default value for option: '${complexOption.name}' => ${invalidArguments

package/src/runtime/parser.ts

@@ -11,6 +11,8 @@ import {
   validateGlobalCommandArgumentValue,
   validateOptionValue,
   validatePositionalValue,
+  runCustomValidation,
+  type DeferredCustomValidation,
 } from "./values/argumentValueValidation.ts";
 import getLogger from "../util/logger.ts";
 import { redactGlobalCommandValue, redactSubCommandValues } from "../util/secretRedaction.ts";
@@ -64,12 +66,14 @@ export function parseSubCommandClause(
   }
 
   if (invalidArguments.length === 0) {
+    const deferred: Array<DeferredCustomValidation> = [];
     // validate the option values
     command.options.forEach((option) => {
       const validatedValue = validateOptionValue(
         option,
         populatedArgumentValues[option.name] || option.defaultValue,
         invalidArguments,
+        deferred,
       );
       if (validatedValue !== undefined) {
         populatedArgumentValues[option.name] = validatedValue;
@@ -89,11 +93,16 @@ export function parseSubCommandClause(
           positional,
           populatedArgumentValues[positional.name] as ValueType,
           invalidArguments,
+          deferred,
         );
         if (validatedValue !== undefined) {
           populatedArgumentValues[positional.name] = validatedValue;
         }
       });
+      if (invalidArguments.length === 0) {
+        // custom validators run once all built-in validation has passed and see all values
+        runCustomValidation(deferred, command, populatedArgumentValues, invalidArguments);
+      }
       logger.debug(
         "Command arguments after positionals validated: %O with invalid args: %O",
         redactSubCommandValues(command, populatedArgumentValues),
@@ -162,14 +171,19 @@ export function parseGlobalCommandClause(
 
   // don't validate the value if the argument is already invalid
   if (invalidArguments.length === 0) {
+    const deferred: Array<DeferredCustomValidation> = [];
     const validatedValue = validateGlobalCommandArgumentValue(
       command,
       populatedArgumentValue,
       invalidArguments,
+      deferred,
     );
     if (validatedValue !== undefined) {
       populatedArgumentValue = validatedValue;
     }
+    if (invalidArguments.length === 0) {
+      runCustomValidation(deferred, command, populatedArgumentValue, invalidArguments);
+    }
   }
 
   logger.debug(

package/src/runtime/values/argumentValueValidation.ts

@@ -16,6 +16,7 @@ import { InvalidArgumentReason } from "@flowscripter/dynamic-cli-framework-api";
 import type { SubCommandArgument } from "@flowscripter/dynamic-cli-framework-api";
 import type { Argument } from "@flowscripter/dynamic-cli-framework-api";
 import type { GlobalCommand } from "@flowscripter/dynamic-cli-framework-api";
+import type { Command } from "@flowscripter/dynamic-cli-framework-api";
 
 interface ValidationResult {
   invalidArgument?: InvalidArgument;
@@ -41,32 +42,61 @@ function withPrefix(invalidArgument: InvalidArgument, prefix: string): InvalidAr
 }
 
 /**
- * Invokes the custom validate function (if any) of the provided {@link Argument} and returns an
- * {@link InvalidArgument} if the custom validation failed.
- *
- * @param argument the {@link Argument} providing the custom validate function.
- * @param name the name to use for the {@link InvalidArgument}.
- * @param value the validated and type-converted value.
+ * A custom validation to be invoked once all built-in validation has passed.
+ */
+export interface DeferredCustomValidation {
+  readonly argument: Argument | ComplexOption;
+  readonly path: string;
+  readonly value: SingleValueType | Values | Array<SingleValueType | Values>;
+}
+
+/**
+ * Records a custom validation of the provided {@link Argument} (if it has one) for later invocation by
+ * {@link runCustomValidation}. Deferred validations are recorded bottom-up and depth-first.
  */
-function doCustomValidation(
+function deferCustomValidation(
+  deferred: Array<DeferredCustomValidation> | undefined,
   argument: Argument | ComplexOption,
-  name: string,
+  path: string,
   value: SingleValueType | Values | Array<SingleValueType | Values>,
-): InvalidArgument | undefined {
-  if (argument.validate === undefined) {
-    return undefined;
+): void {
+  if (deferred !== undefined && argument.validate !== undefined) {
+    deferred.push({ argument, path, value });
   }
-  const message = argument.validate(value as ValueType | Values | Array<Values>);
-  if (message === undefined) {
-    return undefined;
+}
+
+/**
+ * Invokes the recorded custom validations in order, stopping at the first failure.
+ *
+ * @param deferred the validations recorded while validating the values of the command.
+ * @param command the {@link Command} the validated values belong to.
+ * @param values all validated and converted values of the command.
+ * @param invalidArguments an array of {@link InvalidArgument} which is added to if a custom validation fails.
+ */
+export function runCustomValidation(
+  deferred: ReadonlyArray<DeferredCustomValidation>,
+  command: Command,
+  values: PopulatedValues | PopulatedSingleValueType,
+  invalidArguments: Array<InvalidArgument>,
+): void {
+  for (const { argument, path, value } of deferred) {
+    const message = argument.validate!(value as ValueType | Values | Array<Values>, {
+      argument: argument as Argument,
+      path,
+      values,
+      command,
+    });
+    if (message !== undefined) {
+      invalidArguments.push({
+        argument,
+        name: path,
+        value: value as PopulatedValueType | PopulatedValues,
+        reason: InvalidArgumentReason.CUSTOM_VALIDATION,
+        message,
+      });
+      return;
+    }
   }
-  return {
-    argument,
-    name,
-    value: value as PopulatedValueType | PopulatedValues,
-    reason: InvalidArgumentReason.CUSTOM_VALIDATION,
-    message,
-  };
 }
 
 /**
@@ -193,6 +223,8 @@ function validatePrimitiveValue(
 function validateArrayValue(
   subCommandArgument: SubCommandArgument | ComplexOption,
   arrayValue: Array<PopulatedSingleValueType | PopulatedValues | undefined>,
+  path: string,
+  deferred: Array<DeferredCustomValidation> | undefined,
 ): ArrayValueValidationResult {
   const convertedArrayValue: Array<SingleValueType | Values> = [];
 
@@ -228,7 +260,12 @@ function validateArrayValue(
           },
         };
       }
-      validationResult = validateObjectValue(subCommandArgument as ComplexOption, singleValue);
+      validationResult = validateObjectValue(
+        subCommandArgument as ComplexOption,
+        singleValue,
+        `${path}[${i}]`,
+        deferred,
+      );
     } // if not array and not object, then must be primitive
     else {
       if (isComplexOption(subCommandArgument)) {
@@ -267,11 +304,14 @@ function validateArrayValue(
 function validateObjectValue(
   argument: ComplexOption,
   objectValue: PopulatedValues,
+  path: string,
+  deferred: Array<DeferredCustomValidation> | undefined,
 ): ObjectValueValidationResult {
   const convertedObjectValue: Values = {};
 
   for (let i = 0; i < argument.properties.length; i++) {
     const propertyArg = argument.properties[i]!;
+    const propertyPath = `${path}.${propertyArg.name}`;
     let propertyValue = objectValue[propertyArg.name];
 
     if (propertyValue === undefined && propertyArg.defaultValue !== undefined) {
@@ -311,6 +351,8 @@ function validateObjectValue(
       validationResult = validateArrayValue(
         propertyArg as ComplexOption | SubCommandArgument,
         propertyValue,
+        propertyPath,
+        deferred,
       );
     } else if (typeof propertyValue === "object") {
       if (propertyArg.type !== ComplexValueTypeName.COMPLEX) {
@@ -327,6 +369,8 @@ function validateObjectValue(
       validationResult = validateObjectValue(
         propertyArg as ComplexOption,
         propertyValue as PopulatedValues,
+        propertyPath,
+        deferred,
       );
     } // if not array and not object, then must be primitive
     else {
@@ -356,18 +400,8 @@ function validateObjectValue(
         invalidArgument: withPrefix(validationResult.invalidArgument, `.${propertyArg.name}`),
       };
     }
-    // custom validation runs only once the property (and any nested properties) passed validation
-    const customInvalidArgument = doCustomValidation(
-      propertyArg,
-      `.${propertyArg.name}`,
-      validationResult.validValue!,
-    );
-    if (customInvalidArgument !== undefined) {
-      return {
-        validValue: convertedObjectValue,
-        invalidArgument: customInvalidArgument,
-      };
-    }
+    // custom validation is deferred until all built-in validation has passed
+    deferCustomValidation(deferred, propertyArg, propertyPath, validationResult.validValue!);
   }
   return {
     validValue: convertedObjectValue,
@@ -380,6 +414,7 @@ function doSubCommandArgumentValidation(
   isArray: boolean,
   isOptional: boolean,
   invalidArguments: Array<InvalidArgument>,
+  deferred: Array<DeferredCustomValidation> | undefined,
 ): PopulatedValueType | PopulatedValues | Array<PopulatedValues> {
   // if there is a value, check if it is valid
   if (value !== undefined) {
@@ -395,7 +430,7 @@ function doSubCommandArgumentValidation(
         });
         return undefined;
       }
-      validationResult = validateArrayValue(argument, value);
+      validationResult = validateArrayValue(argument, value, argument.name, deferred);
     } else if (typeof value === "object") {
       if (!isComplexOption(argument)) {
         invalidArguments.push({
@@ -406,7 +441,7 @@ function doSubCommandArgumentValidation(
         });
         return undefined;
       }
-      validationResult = validateObjectValue(argument, value);
+      validationResult = validateObjectValue(argument, value, argument.name, deferred);
     } else {
       if (isComplexOption(argument)) {
         invalidArguments.push({
@@ -424,15 +459,7 @@ function doSubCommandArgumentValidation(
       invalidArguments.push(withPrefix(validationResult.invalidArgument, argument.name));
       return undefined;
     }
-    const customInvalidArgument = doCustomValidation(
-      argument,
-      argument.name,
-      validationResult.validValue!,
-    );
-    if (customInvalidArgument !== undefined) {
-      invalidArguments.push(customInvalidArgument);
-      return undefined;
-    }
+    deferCustomValidation(deferred, argument, argument.name, validationResult.validValue!);
     return validationResult.validValue as PopulatedValueType | PopulatedValues | undefined;
   }
 
@@ -453,11 +480,13 @@ function doSubCommandArgumentValidation(
  * @param option the {@link Option} to validate against.
  * @param value the value (if any) for the {@link Option}.
  * @param invalidArguments an array of {@link InvalidArgument} which may be added to if the provided value is invalid.
+ * @param deferred if provided, custom validations are recorded here for later invocation by {@link runCustomValidation}. If omitted, custom validations are not invoked.
  */
 export function validateOptionValue(
   option: Option | ComplexOption,
   value: PopulatedValueType | PopulatedValues | Array<PopulatedValues | undefined>,
   invalidArguments: Array<InvalidArgument>,
+  deferred?: Array<DeferredCustomValidation>,
 ): PopulatedValueType | PopulatedValues | Array<PopulatedValues> {
   return doSubCommandArgumentValidation(
     option,
@@ -465,6 +494,7 @@ export function validateOptionValue(
     option.isArray || false,
     option.isOptional || false,
     invalidArguments,
+    deferred,
   );
 }
 
@@ -474,11 +504,13 @@ export function validateOptionValue(
  * @param positional the {@link Positional} to validate against.
  * @param value the value (if any) for the {@link Positional}.
  * @param invalidArguments an array of {@link InvalidArgument} which may be added to if the provided value is invalid.
+ * @param deferred if provided, custom validations are recorded here for later invocation by {@link runCustomValidation}. If omitted, custom validations are not invoked.
  */
 export function validatePositionalValue(
   positional: Positional,
   value: PopulatedValueType,
   invalidArguments: Array<InvalidArgument>,
+  deferred?: Array<DeferredCustomValidation>,
 ): PopulatedValueType {
   return doSubCommandArgumentValidation(
     positional,
@@ -486,6 +518,7 @@ export function validatePositionalValue(
     positional.isVarargMultiple || false,
     positional.isVarargOptional || false,
     invalidArguments,
+    deferred,
   ) as PopulatedValueType;
 }
 
@@ -496,11 +529,13 @@ export function validatePositionalValue(
  * @param globalCommand the {@link GlobalCommand} providing the {@link GlobalCommandArgument}.
  * @param value the value (if any) for the {@link GlobalCommandArgument}.
  * @param invalidArguments an array of {@link InvalidArgument} which may be added to if the provided value is invalid.
+ * @param deferred if provided, custom validations are recorded here for later invocation by {@link runCustomValidation}. If omitted, custom validations are not invoked.
  */
 export function validateGlobalCommandArgumentValue(
   globalCommand: GlobalCommand,
   value: PopulatedSingleValueType,
   invalidArguments: Array<InvalidArgument>,
+  deferred?: Array<DeferredCustomValidation>,
 ): PopulatedSingleValueType {
   // if this function is called it is because the argument is defined
   const globalCommandArgument = globalCommand.argument!;
@@ -527,15 +562,12 @@ export function validateGlobalCommandArgumentValue(
       return undefined;
     }
 
-    const customInvalidArgument = doCustomValidation(
+    deferCustomValidation(
+      deferred,
       globalCommandArgument,
       globalCommand.name,
       validationResult.validValue!,
     );
-    if (customInvalidArgument !== undefined) {
-      invalidArguments.push(customInvalidArgument);
-      return undefined;
-    }
     return validationResult.validValue as PopulatedSingleValueType;
   }
 

package/src/service/argumentPrompter/DefaultArgumentPrompterService.ts

@@ -14,7 +14,9 @@ import {
   ComplexValueTypeName,
   type PopulatedSingleValueType,
   type PopulatedValues,
+  type Values,
 } from "@flowscripter/dynamic-cli-framework-api";
+import type { Command } from "@flowscripter/dynamic-cli-framework-api";
 import type { Argument } from "@flowscripter/dynamic-cli-framework-api";
 import type { Option } from "@flowscripter/dynamic-cli-framework-api";
 import type { Positional } from "@flowscripter/dynamic-cli-framework-api";
@@ -23,6 +25,20 @@ import type { SubCommand } from "@flowscripter/dynamic-cli-framework-api";
 import type { GlobalCommand } from "@flowscripter/dynamic-cli-framework-api";
 import { isGlobalCommand, isSubCommand } from "../../runtime/command/CommandTypeGuards.ts";
 
+/**
+ * The command and values visible to {@link Argument.validate} functions while prompting.
+ */
+interface PromptScope {
+  readonly command: Command;
+  readonly values: PopulatedValues | PopulatedSingleValueType;
+}
+
+/**
+ * Used as {@link ValidationContext.command} when prompting via {@link ArgumentPrompterService.promptForArguments},
+ * which is not associated with a specific command.
+ */
+const NO_COMMAND = { name: "" } as Command;
+
 export default class DefaultArgumentPrompterService implements ArgumentPrompterService {
   readonly #prompterService: PrompterService;
 
@@ -63,6 +79,53 @@ export default class DefaultArgumentPrompterService implements ArgumentPrompterS
     return parseResult;
   }
 
+  async promptForArguments(
+    args: ReadonlyArray<Option | ComplexOption>,
+    existing: Values = {},
+  ): Promise<Values | undefined> {
+    if (!this.#prompterService.promptEnabled) {
+      return undefined;
+    }
+    const prompted: Record<string, Values[string]> = {};
+    const merged: Record<string, Values[string]> = { ...existing };
+    const scope: PromptScope = { command: NO_COMMAND, values: merged as PopulatedValues };
+
+    for (const arg of args) {
+      if (arg.name in existing) {
+        continue;
+      }
+      const value = (await this.#promptForArgument(arg.name, arg, scope)) as Values[string];
+      prompted[arg.name] = value;
+      merged[arg.name] = value;
+    }
+    return prompted as Values;
+  }
+
+  async #promptForArgument(
+    name: string,
+    arg: Option | Positional | ComplexOption,
+    scope: PromptScope,
+  ): Promise<PopulatedValues[string]> {
+    if ("type" in arg && (arg as ComplexOption).type === ComplexValueTypeName.COMPLEX) {
+      return await this.#promptForComplexOption(name, arg as ComplexOption, scope);
+    }
+    if (DefaultArgumentPrompterService.#isArrayArgument(arg)) {
+      return await this.#promptForArrayArgument(name, arg as Option | Positional, scope);
+    }
+    const prompt = DefaultArgumentPrompterService.#argumentToPrompt(
+      name,
+      (arg as Option | Positional).description ?? name,
+      arg as Argument,
+      name,
+      scope,
+    );
+    const result = await this.#prompterService.prompt(prompt);
+    return DefaultArgumentPrompterService.#coerceValue(
+      result.value as SingleValueType,
+      (arg as Argument).type,
+    );
+  }
+
   async #promptForGlobalCommand(parseResult: ParseResult): Promise<ParseResult> {
     const command = parseResult.command as GlobalCommand;
     if (!command.argument) {
@@ -73,6 +136,8 @@ export default class DefaultArgumentPrompterService implements ArgumentPrompterS
       command.name,
       command.name,
       command.argument,
+      command.name,
+      { command, values: undefined },
     );
     const result = await this.#prompterService.prompt(prompt);
     const value = DefaultArgumentPrompterService.#coerceValue(
@@ -96,6 +161,7 @@ export default class DefaultArgumentPrompterService implements ArgumentPrompterS
       ...existingValues,
     };
     const remainingInvalid: InvalidArgument[] = [];
+    const scope: PromptScope = { command, values: newValues as PopulatedValues };
 
     for (const invalid of parseResult.invalidArguments) {
       if (invalid.reason !== InvalidArgumentReason.MISSING_VALUE || !invalid.name) {
@@ -109,30 +175,7 @@ export default class DefaultArgumentPrompterService implements ArgumentPrompterS
         continue;
       }
 
-      if ("type" in arg && (arg as ComplexOption).type === ComplexValueTypeName.COMPLEX) {
-        const complexValues = await this.#promptForComplexOption(
-          invalid.name,
-          arg as ComplexOption,
-        );
-        newValues[invalid.name] = complexValues;
-      } else if (DefaultArgumentPrompterService.#isArrayArgument(arg)) {
-        const arrayValues = await this.#promptForArrayArgument(
-          invalid.name,
-          arg as Option | Positional,
-        );
-        newValues[invalid.name] = arrayValues;
-      } else {
-        const prompt = DefaultArgumentPrompterService.#argumentToPrompt(
-          invalid.name,
-          (arg as Option | Positional).description ?? invalid.name,
-          arg as Argument,
-        );
-        const result = await this.#prompterService.prompt(prompt);
-        newValues[invalid.name] = DefaultArgumentPrompterService.#coerceValue(
-          result.value as SingleValueType,
-          (arg as Argument).type,
-        );
-      }
+      newValues[invalid.name] = await this.#promptForArgument(invalid.name, arg, scope);
     }
 
     return {
@@ -147,6 +190,7 @@ export default class DefaultArgumentPrompterService implements ArgumentPrompterS
   async #promptForComplexOption(
     name: string,
     complexOption: ComplexOption,
+    scope: PromptScope,
   ): Promise<PopulatedValues> {
     const values: Record<string, PopulatedValues[string]> = {};
 
@@ -155,6 +199,7 @@ export default class DefaultArgumentPrompterService implements ArgumentPrompterS
         values[(prop as ComplexOption).name] = await this.#promptForComplexOption(
           `${name}.${(prop as ComplexOption).name}`,
           prop as ComplexOption,
+          scope,
         );
       } else {
         const option = prop as Option;
@@ -165,6 +210,8 @@ export default class DefaultArgumentPrompterService implements ArgumentPrompterS
           `${name}.${option.name}`,
           option.description ?? `${name}.${option.name}`,
           option,
+          `${name}.${option.name}`,
+          scope,
         );
         const result = await this.#prompterService.prompt(prompt);
         values[option.name] = DefaultArgumentPrompterService.#coerceValue(
@@ -180,6 +227,7 @@ export default class DefaultArgumentPrompterService implements ArgumentPrompterS
   async #promptForArrayArgument(
     name: string,
     arg: Option | Positional,
+    scope: PromptScope,
   ): Promise<Array<SingleValueType>> {
     const values: SingleValueType[] = [];
 
@@ -188,6 +236,8 @@ export default class DefaultArgumentPrompterService implements ArgumentPrompterS
         name,
         `${arg.description ?? name}${values.length > 0 ? ` [${values.length + 1}]` : ""}`,
         arg as Argument,
+        name,
+        scope,
       );
       const result = await this.#prompterService.prompt(prompt);
       values.push(
@@ -212,7 +262,13 @@ export default class DefaultArgumentPrompterService implements ArgumentPrompterS
     return values;
   }
 
-  static #argumentToPrompt(name: string, description: string, arg: Argument): Prompt {
+  static #argumentToPrompt(
+    name: string,
+    description: string,
+    arg: Argument,
+    path: string,
+    scope: PromptScope,
+  ): Prompt {
     if (arg.type === ValueTypeName.BOOLEAN) {
       return {
         name,
@@ -240,7 +296,17 @@ export default class DefaultArgumentPrompterService implements ArgumentPrompterS
       returnedValue: "",
       min: arg.minValueInclusive,
       max: arg.maxValueInclusive,
-      validate: arg.validate ? (v) => arg.validate!(v) : undefined,
+      validate: arg.validate
+        ? (v) => {
+            const value = DefaultArgumentPrompterService.#coerceValue(v, arg.type);
+            return arg.validate!(value, {
+              argument: arg,
+              path,
+              values: scope.values === undefined ? value : scope.values,
+              command: scope.command,
+            });
+          }
+        : undefined,
     };
 
     return {

package/src/service/configuration/KeyValueServiceProvider.ts

@@ -226,6 +226,7 @@ export default class KeyValueServiceProvider implements ServiceProvider {
     const scopedKeyValueService = this.getScopedKeyValueService(scopeType, scopeKey);
     return {
       cliConfig: context.cliConfig,
+      isTty: context.isTty,
       getServiceById: (id: string): unknown =>
         id === KEY_VALUE_SERVICE_ID ? scopedKeyValueService : context.getServiceById(id),
       doesServiceExist: (id: string): boolean => context.doesServiceExist(id),

package/src/service/printer/PrinterServiceProvider.ts

@@ -3,7 +3,7 @@ import LogLevelCommand from "./command/LogLevelCommand.ts";
 import type { ServiceInfo, ServiceProvider } from "@flowscripter/dynamic-cli-framework-api";
 import type { PrinterService } from "@flowscripter/dynamic-cli-framework-api";
 import { PRINTER_SERVICE_ID } from "@flowscripter/dynamic-cli-framework-api";
-import DarkModeCommand from "./command/DarkModeCommand.ts";
+import ThemeCommand from "./command/ThemeCommand.ts";
 import NoColorCommand from "./command/NoColorCommand.ts";
 import NoHyperlinksCommand from "./command/NoHyperlinksCommand.ts";
 import type { CLIConfig } from "@flowscripter/dynamic-cli-framework-api";
@@ -18,16 +18,23 @@ export default class PrinterServiceProvider implements ServiceProvider {
   readonly serviceId: string = PRINTER_SERVICE_ID;
   readonly servicePriority: number;
   readonly printerService: PrinterService;
+  readonly detectDarkBackground: (() => Promise<boolean | undefined>) | undefined;
 
   /**
    * Create an instance of the service provider with the specified details.
    *
    * @param servicePriority the priority of the service.
    * @param printerService the PrinterService implementation to use.
+   * @param detectDarkBackground optional function detecting whether the terminal background is dark.
    */
-  public constructor(servicePriority: number, printerService: PrinterService) {
+  public constructor(
+    servicePriority: number,
+    printerService: PrinterService,
+    detectDarkBackground?: () => Promise<boolean | undefined>,
+  ) {
     this.servicePriority = servicePriority;
     this.printerService = printerService;
+    this.detectDarkBackground = detectDarkBackground;
   }
 
   public getServiceInfo(_cliConfig: CLIConfig): Promise<ServiceInfo> {
@@ -35,8 +42,8 @@ export default class PrinterServiceProvider implements ServiceProvider {
       service: this.printerService,
       commands: [
         new NoHyperlinksCommand(this.servicePriority + 3),
-        new DarkModeCommand(this.servicePriority + 2),
-        new NoColorCommand(this.servicePriority + 1),
+        new ThemeCommand(this.servicePriority + 1, this.detectDarkBackground),
+        new NoColorCommand(this.servicePriority + 2),
         new LogLevelCommand(this.servicePriority),
       ],
     });