@flowscripter/dynamic-cli-framework 1.7.3 → 1.7.5

package/dist/src/runtime/command/CommandValidator.js

@@ -0,0 +1,371 @@
+import { isGroupCommand, isSubCommand } from "./CommandTypeGuards.js";
+import { ArgumentValueTypeName, ComplexValueTypeName, } from "../../api/argument/ArgumentValueTypes.js";
+import { isComplexOption } from "../argument/ArgumentTypeGuards.js";
+import { getInvalidArgumentString, validateGlobalCommandArgumentValue, validateOptionValue, } from "../values/argumentValueValidation.js";
+import getLogger from "../../util/logger.js";
+import { getGlobalCommandArgumentConfigurationKey, getSubCommandArgumentConfigurationKey, } from "../../util/configHelper.js";
+const logger = getLogger("commandValidation");
+function validateValueType(type, value, argumentName, isDefaultValue, isRangeValue) {
+    switch (type) {
+        case ArgumentValueTypeName.BOOLEAN:
+            if (typeof value !== "boolean") {
+                throw new Error(`Specified ${isDefaultValue ? "default" : "allowable"} value: '${value}' for argument: '${argumentName}' should be a boolean`);
+            }
+            break;
+        case ArgumentValueTypeName.NUMBER:
+            if (typeof value !== "number" || !Number.isFinite(value)) {
+                throw new Error(`Specified ${isDefaultValue ? "default" : isRangeValue ? "range" : "allowable"} value: '${value}' for argument: '${argumentName}' should be a finite number`);
+            }
+            break;
+        case ArgumentValueTypeName.INTEGER:
+            if (typeof value !== "number" || !Number.isInteger(value)) {
+                throw new Error(`Specified ${isDefaultValue ? "default" : isRangeValue ? "range" : "allowable"} value: '${value}' for argument: '${argumentName}' should be an integer`);
+            }
+            break;
+        case ArgumentValueTypeName.STRING:
+            if (typeof value !== "string") {
+                throw new Error(`Specified ${isDefaultValue ? "default" : "allowable"} value: '${value}' for argument: '${argumentName}' should be a string`);
+            }
+            break;
+    }
+}
+function isAlphaNumeric(value) {
+    return value.match(/^[a-z0-9]$/i) !== null;
+}
+function isAlphaNumericOrDashOrUnderscore(value) {
+    return value.match(/^[a-z0-9\-_]+$/i) !== null;
+}
+function isUppercaseAlphaNumericOrUnderscore(value) {
+    return value.match(/^[A-Z0-9_]+$/) !== null;
+}
+function isNameLegal(name) {
+    return name.length > 0 && isAlphaNumericOrDashOrUnderscore(name) && name[0] !== "-";
+}
+function isConfigurationKeyLegal(configurationKey) {
+    return (configurationKey.length > 0 &&
+        isUppercaseAlphaNumericOrUnderscore(configurationKey) &&
+        !configurationKey[0].match(/[0-9]/));
+}
+function validateArgument(argument, name) {
+    if (argument.type !== ArgumentValueTypeName.NUMBER &&
+        argument.type !== ArgumentValueTypeName.INTEGER &&
+        argument.type !== ArgumentValueTypeName.STRING &&
+        argument.type !== ArgumentValueTypeName.BOOLEAN) {
+        throw new Error(`Illegal type: '${argument.type}' for argument: '${name}'`);
+    }
+    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, 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(subCommandArgument) {
+    if (!isNameLegal(subCommandArgument.name)) {
+        throw new Error(`Illegal argument name: '${subCommandArgument.name}'`);
+    }
+    return validateArgument(subCommandArgument, subCommandArgument.name);
+}
+export default class CommandValidator {
+    #cliConfig;
+    #configurationKeys = [];
+    constructor(cliConfig) {
+        this.#cliConfig = cliConfig;
+    }
+    /**
+     * Validates the provided {@link Command}.
+     *
+     * @param command the {@link Command} to validate.
+     *
+     * @throws {Error} if the provided command does not pass validation.
+     */
+    validate(command) {
+        logger.debug("Validating command: %s", command.name);
+        if (isSubCommand(command)) {
+            this.#validateSubCommand(command);
+        }
+        else if (isGroupCommand(command)) {
+            this.#validateGroupCommand(command);
+        }
+        else {
+            this.#validateGlobalCommand(command);
+        }
+    }
+    /**
+     * Validates the provided {@link GlobalCommand} or by extension {@link GlobalModifierCommand}.
+     *
+     * @param globalCommand the {@link GlobalCommand} to validate.
+     *
+     * @throws {Error} if:
+     * * the {@link Command.name} does not consist only of alphanumeric non-whitespace ASCII characters or `_` and `-`
+     * characters.
+     * * the {@link Command.name} starts with `-`.
+     * * the {@link GlobalCommand.shortAlias} does not consist of a single alphanumeric non-whitespace ASCII character.
+     * * the {@link GlobalCommand.argument} is defined and it is not valid.
+     */
+    #validateGlobalCommand(globalCommand) {
+        if (!isNameLegal(globalCommand.name)) {
+            throw new Error(`Illegal global command name: '${globalCommand.name}'`);
+        }
+        if (globalCommand.shortAlias &&
+            (globalCommand.shortAlias.length !== 1 || !isAlphaNumeric(globalCommand.shortAlias))) {
+            throw new Error(`Illegal short alias: '${globalCommand.shortAlias}' for global command: '${globalCommand.name}'`);
+        }
+        if (globalCommand.argument) {
+            const { argument } = globalCommand;
+            validateArgument(argument, globalCommand.name);
+            if (argument.defaultValue) {
+                const invalidArguments = [];
+                validateGlobalCommandArgumentValue(globalCommand, argument.defaultValue, invalidArguments);
+                if (invalidArguments.length > 0) {
+                    throw new Error(`Illegal default value for global command: '${globalCommand.name}' => ${invalidArguments
+                        .map((invalidArgument) => getInvalidArgumentString(invalidArgument, true))
+                        .join(", ")}`);
+                }
+            }
+            this.#validateGlobalCommandArgumentConfigurationKey(globalCommand, argument);
+        }
+    }
+    /**
+     * Validates the provided {@link GroupCommand}.
+     *
+     * @param groupCommand the {@link GroupCommand} to validate.
+     *
+     * @throws {Error} if:
+     * * the {@link Command.name} does not consist only of alphanumeric non-whitespace ASCII characters or `_` and `-`
+     * characters.
+     * * the {@link Command.name} starts with `-`.
+     * * {@link GroupCommand.memberSubCommands} is empty.
+     * * any of the member {@link SubCommand} instances are themselves not valid.
+     * * any of the member {@link SubCommand} instances define duplicate names.
+     * * any of the member {@link SubCommand} instances define a name which duplicates the group command name.
+     */
+    #validateGroupCommand(groupCommand) {
+        if (!isNameLegal(groupCommand.name)) {
+            throw new Error(`Illegal group command name: '${groupCommand.name}'`);
+        }
+        if (groupCommand.memberSubCommands.length === 0) {
+            throw new Error(`Group command: '${groupCommand.name}' has no member sub-commands`);
+        }
+        const subCommandNames = [];
+        groupCommand.memberSubCommands.forEach((subCommand) => {
+            if (subCommandNames.includes(subCommand.name)) {
+                throw new Error(`Group command: '${groupCommand.name}' contains member sub-commands with duplicate name: '${subCommand.name}'`);
+            }
+            if (subCommand.name === groupCommand.name) {
+                throw new Error(`Group command: '${groupCommand.name}' contains member sub-command with the same name`);
+            }
+            subCommandNames.push(subCommand.name);
+            this.#validateSubCommand(subCommand);
+        });
+    }
+    /**
+     * Validates the provided {@link SubCommand}.
+     *
+     * @param subCommand the {@link SubCommand} to validate.
+     *
+     * @throws {Error} if:
+     * the {@link Command.name} does not consist only of alphanumeric non-whitespace ASCII characters or `_` and `-`
+     characters.
+     * the {@link Command.name} starts with `-`.
+     * * any [[SubCommandArgument.name]] name does not consist only of alphanumeric non-whitespace ASCII characters
+     * or `_` and `-` characters or starts with `-`.
+     * * any entry in {@link SubCommand.options} is not valid.
+     * * any entry in {@link SubCommand.positionals} is not valid.
+     * * there are duplicate names in the {@link SubCommandArgument} instances defined by {@link SubCommand.options} and
+     * {@link SubCommand.positionals}.
+     * * there are duplicate property paths defined by {@link Argument.name} and {@link Option.shortAlias} entries in nested
+     * {@link ComplexOption} instances.
+     */
+    #validateSubCommand(subCommand) {
+        if (!isNameLegal(subCommand.name)) {
+            throw new Error(`Illegal sub-command name: '${subCommand.name}'`);
+        }
+        const argumentNames = [];
+        const optionAliases = [];
+        const allOptionPaths = [];
+        if (subCommand.options) {
+            subCommand.options.forEach((option) => {
+                if (argumentNames.includes(option.name)) {
+                    throw new Error(`Sub-command: '${subCommand.name}' contains arguments with the same name: '${option.name}'`);
+                }
+                argumentNames.push(option.name);
+                const currentOptionPaths = [""];
+                if (option.shortAlias) {
+                    if (argumentNames.includes(option.shortAlias)) {
+                        throw new Error(`Sub-command: '${subCommand.name}' contains arguments with the same name and short alias: '${option.shortAlias}'`);
+                    }
+                    if (optionAliases.includes(option.shortAlias)) {
+                        throw new Error(`Sub-command: '${subCommand.name}' contains arguments with the same short alias: '${option.shortAlias}'`);
+                    }
+                    optionAliases.push(option.shortAlias);
+                }
+                this.#validateOptionOrComplexOption(subCommand, option, currentOptionPaths, allOptionPaths, []);
+            });
+        }
+        if (subCommand.positionals) {
+            for (let i = 0; i < subCommand.positionals.length; i += 1) {
+                const positional = subCommand.positionals[i];
+                validateSubCommandArgument(positional);
+                if (argumentNames.includes(positional.name)) {
+                    throw new Error(`Sub-command: '${subCommand.name}' contains arguments with the same name: '${positional.name}'`);
+                }
+                argumentNames.push(positional.name);
+                if (i < subCommand.positionals.length - 1 &&
+                    (positional.isVarargOptional || positional.isVarargMultiple)) {
+                    throw new Error(`Positional: '${positional.name}' for the command: '${subCommand.name}' is defined as a vararg but it is not the last positional argument`);
+                }
+                this.#validateSubCommandArgumentConfigurationKey(subCommand, [positional]);
+            }
+        }
+    }
+    #validateSubCommandArgumentConfigurationKey(command, argumentAncestry) {
+        const argument = argumentAncestry[argumentAncestry.length - 1];
+        if (command.enableConfiguration === true) {
+            if (argument.configurationKey !== undefined &&
+                !isConfigurationKeyLegal(argument.configurationKey)) {
+                throw new Error(`Illegal configuration key: '${argument.configurationKey}'`);
+            }
+            const configurationKey = getSubCommandArgumentConfigurationKey(this.#cliConfig, command, argumentAncestry);
+            if (configurationKey !== undefined) {
+                if (this.#configurationKeys.includes(configurationKey)) {
+                    throw new Error(`Command: '${command.name}' contains arguments with the same configuration key: '${configurationKey}'`);
+                }
+                this.#configurationKeys.push(configurationKey);
+            }
+        }
+        else if (argument.configurationKey !== undefined) {
+            throw new Error(`Command: '${command.name}' enableConfiguration is false, but an argument defines a configurationKey: '${argument.configurationKey}'`);
+        }
+    }
+    #validateGlobalCommandArgumentConfigurationKey(command, globalCommandArgument) {
+        if (command.enableConfiguration === true) {
+            if (globalCommandArgument.configurationKey !== undefined &&
+                !isConfigurationKeyLegal(globalCommandArgument.configurationKey)) {
+                throw new Error(`Illegal configuration key: '${globalCommandArgument.configurationKey}'`);
+            }
+            const configurationKey = getGlobalCommandArgumentConfigurationKey(this.#cliConfig, command, globalCommandArgument);
+            if (configurationKey !== undefined) {
+                if (this.#configurationKeys.includes(configurationKey)) {
+                    throw new Error(`Command: '${command.name}' contains arguments with the same configuration key: '${configurationKey}'`);
+                }
+                this.#configurationKeys.push(configurationKey);
+            }
+        }
+        else if (globalCommandArgument.configurationKey !== undefined) {
+            throw new Error(`Command: '${command.name}' enableConfiguration is false, but an argument defines a configurationKey: '${globalCommandArgument.configurationKey}'`);
+        }
+    }
+    #validateOptionOrComplexOption(subCommand, option, currentOptionPaths, allOptionPaths, argumentAncestry) {
+        if (option.shortAlias &&
+            (option.shortAlias.length !== 1 || !isAlphaNumeric(option.shortAlias))) {
+            throw new Error(`Illegal short alias: '${option.shortAlias}' for option: '${option.name}'`);
+        }
+        if (isComplexOption(option)) {
+            this.#validateComplexOption(subCommand, option, currentOptionPaths, allOptionPaths, [
+                ...argumentAncestry,
+                option,
+            ]);
+        }
+        else {
+            this.#validateOption(option, currentOptionPaths, allOptionPaths);
+            this.#validateSubCommandArgumentConfigurationKey(subCommand, [...argumentAncestry, option]);
+        }
+    }
+    #validateOption(option, currentOptionPaths, allOptionPaths) {
+        validateSubCommandArgument(option);
+        if (Array.isArray(option.defaultValue) && !option.isArray) {
+            throw new Error(`Illegal array default value: '${option.defaultValue.join(",")}' for non-array option: '${option.name}'`);
+        }
+        if (option.defaultValue) {
+            const invalidArguments = [];
+            validateOptionValue(option, option.defaultValue, invalidArguments);
+            if (invalidArguments.length > 0) {
+                throw new Error(`Illegal default value for option: '${option.name}' => ${invalidArguments
+                    .map((invalidArgument) => getInvalidArgumentString(invalidArgument, true))
+                    .join(", ")}`);
+            }
+        }
+        currentOptionPaths.forEach((currentOptionPath) => {
+            const leafPath = `${currentOptionPath}.${option.name}`;
+            if (allOptionPaths.includes(leafPath)) {
+                throw new Error(`Duplicate nested option path: '${leafPath}' discovered for option: '${option.name}'`);
+            }
+            allOptionPaths.push(leafPath);
+        });
+        if (option.shortAlias) {
+            currentOptionPaths.forEach((currentOptionPath) => {
+                const leafPath = `${currentOptionPath}.${option.shortAlias}`;
+                if (allOptionPaths.includes(leafPath)) {
+                    throw new Error(`Duplicate nested option path: '${leafPath}' discovered for option: '${option.name}'`);
+                }
+                allOptionPaths.push(leafPath);
+            });
+        }
+    }
+    #validateComplexOption(subCommand, complexOption, currentOptionPaths, allOptionPaths, argumentAncestry) {
+        if (!isNameLegal(complexOption.name)) {
+            throw new Error(`Illegal complex option name: '${complexOption.name}'`);
+        }
+        if (complexOption.type !== ComplexValueTypeName.COMPLEX) {
+            throw new Error(`Illegal type: '${complexOption.type}' for complex option: '${complexOption.name}'`);
+        }
+        if (Array.isArray(complexOption.defaultValue) && !complexOption.isArray) {
+            throw new Error(`Illegal array default value: '${JSON.stringify(complexOption.defaultValue)}' for non-array option: '${complexOption.name}'`);
+        }
+        if (complexOption.defaultValue) {
+            const invalidArguments = [];
+            validateOptionValue(complexOption, complexOption.defaultValue, invalidArguments);
+            if (invalidArguments.length > 0) {
+                throw new Error(`Illegal default value for option: '${complexOption.name}' => ${invalidArguments
+                    .map((invalidArgument) => getInvalidArgumentString(invalidArgument, true))
+                    .join(", ")}`);
+            }
+        }
+        if (complexOption.properties.length === 0) {
+            throw new Error(`Complex option: '${complexOption.name}' has no properties`);
+        }
+        complexOption.properties.forEach((property) => {
+            const newCurrentOptionPaths = [];
+            currentOptionPaths.forEach((currentOptionPath) => {
+                newCurrentOptionPaths.push(`${currentOptionPath}.${property.name}`);
+            });
+            if (property.shortAlias) {
+                currentOptionPaths.forEach((currentOptionPath) => {
+                    newCurrentOptionPaths.push(`${currentOptionPath}.${property.shortAlias}`);
+                });
+            }
+            this.#validateOptionOrComplexOption(subCommand, property, newCurrentOptionPaths, allOptionPaths, [...argumentAncestry, complexOption]);
+        });
+    }
+}

package/dist/src/runtime/parser.js

@@ -0,0 +1,105 @@
+import populateGlobalCommandValue from "./values/globalCommandValuePopulation.js";
+import { validateGlobalCommandArgumentValue, validateOptionValue, validatePositionalValue, } from "./values/argumentValueValidation.js";
+import getLogger from "../util/logger.js";
+import populateSubCommandValues from "./values/subCommandValuePopulation.js";
+const logger = getLogger("parser");
+/**
+ * Parse the arguments for the specified {@link CommandClause} assuming it contains a {@link SubCommand}.
+ *
+ * @param commandClause the clause to parse.
+ * @param defaultValues optional default {@link PopulatedArgumentValues} to use for population before parsing the provided arguments.
+ */
+export function parseSubCommandClause(commandClause, defaultValues) {
+    const command = commandClause.command;
+    const potentialArgs = commandClause.potentialArgs;
+    const groupCommand = commandClause.groupCommand;
+    const invalidArguments = [];
+    // check if we need to process any arguments at all
+    if (command.options.length === 0 && command.positionals.length === 0) {
+        return {
+            command,
+            groupCommand,
+            populatedArgumentValues: {},
+            invalidArguments,
+            unusedArgs: potentialArgs,
+        };
+    }
+    const { populatedArgumentValues, unusedArgs, invalidArgument } = populateSubCommandValues(command, potentialArgs, defaultValues);
+    if (invalidArgument) {
+        invalidArguments.push(invalidArgument);
+    }
+    if (invalidArguments.length === 0) {
+        // validate the option values
+        command.options.forEach((option) => {
+            const validatedValue = validateOptionValue(option, populatedArgumentValues[option.name] || option.defaultValue, invalidArguments);
+            if (validatedValue !== undefined) {
+                populatedArgumentValues[option.name] = validatedValue;
+            }
+        });
+        logger.debug("Command arguments after options validated: %O with invalid args: %O", populatedArgumentValues, invalidArguments);
+        if (invalidArguments.length === 0) {
+            // validate the positional values
+            command.positionals.forEach((positional) => {
+                const validatedValue = validatePositionalValue(positional, populatedArgumentValues[positional.name], invalidArguments);
+                if (validatedValue !== undefined) {
+                    populatedArgumentValues[positional.name] = validatedValue;
+                }
+            });
+            logger.debug("Command arguments after positionals validated: %O with invalid args: %O", populatedArgumentValues, invalidArguments);
+        }
+    }
+    if (groupCommand) {
+        return {
+            command,
+            populatedArgumentValues,
+            groupCommand,
+            invalidArguments,
+            unusedArgs,
+        };
+    }
+    return {
+        command,
+        populatedArgumentValues,
+        invalidArguments,
+        unusedArgs: unusedArgs,
+    };
+}
+/**
+ * Parse the arguments for the specified {@link CommandClause} assuming it contains a {@link GlobalCommand} or {@link GlobalModifierCommand}.
+ *
+ * @param commandClause the clause to parse.
+ * @param defaultValue optional default {@link PopulatedArgumentSingleValueType} to use for population before parsing the provided arguments.
+ */
+export function parseGlobalCommandClause(commandClause, defaultValue) {
+    const command = commandClause.command;
+    const potentialArgs = commandClause.potentialArgs;
+    const invalidArguments = [];
+    // check if we need to process an argument at all
+    if (!command.argument) {
+        return {
+            command,
+            populatedArgumentValues: undefined,
+            invalidArguments,
+            unusedArgs: potentialArgs,
+        };
+    }
+    let { populatedArgumentValue, unusedArgs, invalidArgument } = populateGlobalCommandValue(command, potentialArgs, defaultValue);
+    if (invalidArgument) {
+        invalidArguments.push(invalidArgument);
+    }
+    logger.debug("Command arguments for command: %s after value population: %O with invalid args: %O and unused args: %O", command.name, populatedArgumentValue, invalidArguments, unusedArgs);
+    // don't validate the value if the argument is already invalid
+    if (invalidArguments.length === 0) {
+        const validatedValue = validateGlobalCommandArgumentValue(command, populatedArgumentValue, invalidArguments);
+        if (validatedValue !== undefined) {
+            populatedArgumentValue = validatedValue;
+        }
+    }
+    logger.debug("Command arguments for command: %s after value validation: %O with invalid args: %O", command.name, populatedArgumentValue, invalidArguments);
+    return {
+        command,
+        populatedArgumentValues: populatedArgumentValue,
+        invalidArguments,
+        unusedArgs,
+    };
+}

package/dist/src/runtime/registry/DefaultCommandRegistry.js

@@ -0,0 +1,190 @@
+import { isGlobalCommand, isGlobalModifierCommand, isGroupCommand, isSubCommand, } from "../command/CommandTypeGuards.js";
+import getLogger from "../../util/logger.js";
+const logger = getLogger("DefaultCommandRegistry");
+/**
+ * Default implementation of a {@link CommandRegistry}.
+ */
+export default class DefaultCommandRegistry {
+    #commandValidator;
+    #subCommandsByName = new Map();
+    #groupCommandsByName = new Map();
+    #groupCommandsAndMemberSubCommandsByName = new Map();
+    #globalCommandsByName = new Map();
+    #globalCommandsByShortAlias = new Map();
+    #globalModifierCommandsByName = new Map();
+    #globalModifierCommandsByShortAlias = new Map();
+    #globalModifierCommandsByNameByServiceId = new Map();
+    #globalModifierCommandsByShortAliasByServiceId = new Map();
+    #globalModifierCommandsByNameWithoutServiceId = new Map();
+    #globalModifierCommandsByShortAliasWithoutServiceId = new Map();
+    #nonModifierCommandsByName = new Map();
+    /**
+     * Constructor taking an optional initial list of {@link Command} instances to register.
+     *
+     * @param commands optional list of {@link Command} instances.
+     * @param commandValidator optional {@link CommandValidator} to use for all registered {@link Command} instances.
+     */
+    constructor(commands, commandValidator) {
+        this.#commandValidator = commandValidator;
+        commands?.forEach((command) => this.addCommand(command));
+    }
+    /**
+     * Validate a {@link GlobalCommand} or by extension a {@link GlobalModifierCommand} against those registered so far.
+     *
+     * @throws {Error} if the name of the provided {@link GlobalCommand} is already registered.
+     */
+    #validateGlobalCommandWithOtherGlobalCommands(globalCommand) {
+        if (this.#globalCommandsByName.has(globalCommand.name)) {
+            throw new Error(`Command name: ${globalCommand.name} duplicates the name of an existing command`);
+        }
+        if (this.#globalModifierCommandsByName.has(globalCommand.name)) {
+            throw new Error(`Command name: ${globalCommand.name} duplicates the name of an existing command`);
+        }
+        if (globalCommand.shortAlias !== undefined) {
+            if (this.#globalCommandsByShortAlias.has(globalCommand.shortAlias)) {
+                throw new Error(`Command name: ${globalCommand.shortAlias} duplicates the short alias of an existing command`);
+            }
+            if (this.#globalModifierCommandsByShortAlias.has(globalCommand.shortAlias)) {
+                throw new Error(`Command name: ${globalCommand.shortAlias} duplicates the short alias of an existing command`);
+            }
+        }
+    }
+    /**
+     * Validate a non-global {@link Command} against those registered so far.
+     *
+     * @throws {Error} if the name of the provided {@link Command} is already registered.
+     */
+    #validateNonGlobalCommandWithOtherNonGlobalCommands(command) {
+        if (this.#subCommandsByName.has(command.name)) {
+            throw new Error(`Command name: ${command.name} duplicates the name of an existing command`);
+        }
+        if (this.#groupCommandsByName.has(command.name)) {
+            throw new Error(`Command name: ${command.name} duplicates the name of an existing command`);
+        }
+    }
+    getSubCommands() {
+        return Array.from(this.#subCommandsByName.values());
+    }
+    getGroupCommands() {
+        return Array.from(this.#groupCommandsByName.values());
+    }
+    getGlobalCommands() {
+        return Array.from(this.#globalCommandsByName.values());
+    }
+    getGlobalModifierCommands() {
+        return Array.from(this.#globalModifierCommandsByName.values());
+    }
+    /**
+     * Add a {@link Command} to the registry optionally specifying a service ID if the command
+     * was provided by a {@link ServiceProvider}.
+     *
+     * @param command the {@link Command} to register.
+     * @param serviceId the service ID if the command was provided by a {@link ServiceProvider}.
+     */
+    addCommand(command, serviceId) {
+        logger.debug("Adding command: %s", command.name);
+        if (this.#commandValidator !== undefined) {
+            this.#commandValidator.validate(command);
+        }
+        if (isSubCommand(command)) {
+            this.#validateNonGlobalCommandWithOtherNonGlobalCommands(command);
+            this.#subCommandsByName.set(command.name, command);
+            this.#nonModifierCommandsByName.set(command.name, command);
+            return;
+        }
+        if (isGroupCommand(command)) {
+            this.#validateNonGlobalCommandWithOtherNonGlobalCommands(command);
+            this.#groupCommandsByName.set(command.name, command);
+            this.#nonModifierCommandsByName.set(command.name, command);
+            const groupCommand = command;
+            groupCommand.memberSubCommands.forEach((command) => {
+                this.#groupCommandsAndMemberSubCommandsByName.set(`${groupCommand.name}:${command.name}`, {
+                    groupCommand,
+                    command,
+                });
+            });
+            return;
+        }
+        if (isGlobalCommand(command)) {
+            this.#validateGlobalCommandWithOtherGlobalCommands(command);
+            this.#globalCommandsByName.set(command.name, command);
+            if (command.shortAlias !== undefined) {
+                this.#globalCommandsByShortAlias.set(command.shortAlias, command);
+            }
+            this.#nonModifierCommandsByName.set(command.name, command);
+            return;
+        }
+        if (isGlobalModifierCommand(command)) {
+            this.#validateGlobalCommandWithOtherGlobalCommands(command);
+            this.#globalModifierCommandsByName.set(command.name, command);
+            if (command.shortAlias !== undefined) {
+                this.#globalModifierCommandsByShortAlias.set(command.shortAlias, command);
+            }
+            if (serviceId === undefined) {
+                this.#globalModifierCommandsByNameWithoutServiceId.set(command.name, command);
+                if (command.shortAlias !== undefined) {
+                    this.#globalModifierCommandsByShortAliasWithoutServiceId.set(command.shortAlias, command);
+                }
+            }
+            else {
+                if (!this.#globalModifierCommandsByNameByServiceId.has(serviceId)) {
+                    this.#globalModifierCommandsByNameByServiceId.set(serviceId, new Map());
+                }
+                this.#globalModifierCommandsByNameByServiceId.get(serviceId).set(command.name, command);
+                if (command.shortAlias !== undefined) {
+                    if (!this.#globalModifierCommandsByShortAliasByServiceId.has(serviceId)) {
+                        this.#globalModifierCommandsByShortAliasByServiceId.set(serviceId, new Map());
+                    }
+                    this.#globalModifierCommandsByShortAliasByServiceId
+                        .get(serviceId)
+                        .set(command.shortAlias, command);
+                }
+            }
+            return;
+        }
+    }
+    getSubCommandByName(name) {
+        return this.#subCommandsByName.get(name);
+    }
+    getGroupCommandByName(name) {
+        return this.#groupCommandsByName.get(name);
+    }
+    getGroupCommandAndMemberSubCommandByJoinedName(groupAndMemberSubCommandName) {
+        return this.#groupCommandsAndMemberSubCommandsByName.get(groupAndMemberSubCommandName);
+    }
+    getGlobalCommandByName(name) {
+        return this.#globalCommandsByName.get(name);
+    }
+    getGlobalModifierCommandByName(name) {
+        return this.#globalModifierCommandsByName.get(name);
+    }
+    getGroupAndMemberCommandsByJoinedName() {
+        return this.#groupCommandsAndMemberSubCommandsByName;
+    }
+    getGlobalModifierCommandsByNameProvidedByService(serviceId) {
+        const getGlobalModifierCommandByName = this.#globalModifierCommandsByNameByServiceId.get(serviceId);
+        if (getGlobalModifierCommandByName !== undefined) {
+            return getGlobalModifierCommandByName;
+        }
+        return new Map();
+    }
+    getGlobalModifierCommandsByShortAliasProvidedByService(serviceId) {
+        const getGlobalModifierCommandByShortAlias = this.#globalModifierCommandsByShortAliasByServiceId.get(serviceId);
+        if (getGlobalModifierCommandByShortAlias !== undefined) {
+            return getGlobalModifierCommandByShortAlias;
+        }
+        return new Map();
+    }
+    getGlobalModifierCommandsByNameNotProvidedByService() {
+        return this.#globalModifierCommandsByNameWithoutServiceId;
+    }
+    getGlobalModifierCommandsByShortAliasNotProvidedByService() {
+        return this.#globalModifierCommandsByShortAliasWithoutServiceId;
+    }
+    getNonModifierCommandsByName() {
+        return this.#nonModifierCommandsByName;
+    }
+    getGlobalCommandsByShortAlias() {
+        return this.#globalCommandsByShortAlias;
+    }
+}