blendsdk 5.33.0

package/dist/cmdline/cmdline.js

@@ -0,0 +1,683 @@
+import { isBoolean, isNumeric, isString } from '../stdlib/index.js';
+import path from 'path';
+import { InvalidConfigurationError, MalformedArgumentError } from './errors.js';
+import { getDomainValidationError, getEmailValidationError, isValidDomain, isValidEmail, } from './validators.js';
+/**
+ * @export
+ * @class CommandLineParser
+ */
+export class CommandLineParser {
+    /**
+     * @protected
+     * @type {ICommandLineParser}
+     * @memberof CommandLineParser
+     */
+    config;
+    /**
+     * @protected
+     * @type {string}
+     * @memberof CommandLineParser
+     */
+    interpreter;
+    /**
+     * @protected
+     * @type {string}
+     * @memberof CommandLineParser
+     */
+    script;
+    /**
+     * @protected
+     * @type {string}
+     * @memberof CommandLineParser
+     */
+    scriptName;
+    /**
+     * @protected
+     * @type {ICommand[]}
+     * @memberof CommandLineParser
+     */
+    commands;
+    /**
+     * @protected
+     * @type {IDictionaryOf<IDictionaryOf<any>>}
+     * @memberof CommandLineParser
+     */
+    optionValues;
+    /**
+     * References the current running command
+     *
+     * @protected
+     * @memberof CommandLineParser
+     */
+    currentCommand;
+    /**
+     * Creates an instance of CommandLineParser.
+     * @param {ICommandLineParser} [config]
+     * @memberof CommandLineParser
+     */
+    constructor(config) {
+        this.config = config ?? { name: 'default' };
+        this.config.version = this.config.version ?? '1.0';
+        this.commands = [];
+        this.optionValues = {};
+        this.interpreter = '';
+        this.script = '';
+        this.scriptName = '';
+        this.prepare();
+    }
+    /**
+     * @protected
+     * @param {string[][]} table
+     * @memberof CommandLineParser
+     */
+    print(table) {
+        const res = [];
+        const colSize = [];
+        table.forEach(r => {
+            r.forEach((c, ci) => {
+                const currentSize = colSize[ci] ?? 0;
+                colSize[ci] = c.toString().length > currentSize ? c.toString().length : currentSize;
+            });
+        });
+        table.forEach((r, ri) => {
+            res[ri] = [];
+            r.forEach((c, ci) => {
+                const size = colSize[ci] ?? 0;
+                res[ri][ci] = c.padEnd(size, ' ');
+            });
+        });
+        console.log(res
+            .map(r => {
+            return r.join('').trimEnd();
+        })
+            .join('\n')
+            .trimEnd());
+    }
+    /**
+     * Handles quoted arguments and special characters
+     * @protected
+     * @param {string} arg
+     * @return {string}
+     * @memberof CommandLineParser
+     */
+    processQuotedArgument(arg) {
+        // Handle quoted arguments with spaces
+        if ((arg.startsWith('"') && arg.endsWith('"')) || (arg.startsWith("'") && arg.endsWith("'"))) {
+            return arg.slice(1, -1);
+        }
+        // Handle escaped characters
+        return arg.replace(/\\(.)/g, '$1');
+    }
+    /**
+     * Validates argument format and handles malformed arguments
+     * @protected
+     * @param {string} arg
+     * @memberof CommandLineParser
+     */
+    validateArgument(arg) {
+        // Check for empty arguments
+        if (arg.length === 0) {
+            throw new MalformedArgumentError(arg, 'Empty argument provided');
+        }
+        // Check for malformed options (starting with - but no content)
+        if (arg === '-' || arg === '--') {
+            throw new MalformedArgumentError(arg, 'Invalid option format');
+        }
+        // Check for options with invalid characters
+        if (arg.startsWith('-') && !/^-{1,2}[a-zA-Z][a-zA-Z0-9_-]*(?:=.*)?$/.test(arg)) {
+            // Allow special case for negative numbers
+            if (!/^-\d+(\.\d+)?$/.test(arg)) {
+                throw new MalformedArgumentError(arg, 'Invalid option name format');
+            }
+        }
+    }
+    /**
+     * @protected
+     * @return {IToken[]}
+     * @memberof CommandLineParser
+     */
+    parseTokens() {
+        const [, , ...args] = process.argv;
+        // Validate and process arguments
+        const processedArgs = args.map(arg => {
+            try {
+                this.validateArgument(arg);
+                return this.processQuotedArgument(arg);
+            }
+            catch (error) {
+                if (error instanceof MalformedArgumentError) {
+                    throw error;
+                }
+                throw new MalformedArgumentError(arg, `Failed to process argument: ${error instanceof Error ? error.message : 'Unknown error'}`);
+            }
+        });
+        // Tokenize
+        const optionRe = /^-(-?).*$/;
+        const commandOption = /^[a-zA-Z][a-zA-Z0-9_-]*$/;
+        const pass1 = [];
+        processedArgs.forEach((arg, index) => {
+            const isOption = optionRe.test(arg) && !/^-\d+(\.\d+)?$/.test(arg); // Exclude negative numbers
+            const isCommand = commandOption.test(arg) && index === 0 && !isOption;
+            const isLongOption = isOption && arg.startsWith('--');
+            const isShortOption = isOption && !isLongOption && arg.startsWith('-');
+            const isValue = !isOption && !isCommand;
+            pass1.push({
+                arg,
+                index,
+                isCommand,
+                isOption,
+                isShortOption,
+                isLongOption,
+                isValue,
+            });
+        });
+        const pass2 = [];
+        // Find the option values
+        pass1.forEach(token => {
+            if (token.isShortOption) {
+                const argChars = token.arg.split('');
+                if (argChars.length < 2)
+                    return;
+                const optionChar = argChars[1] ?? '';
+                const parts = argChars.slice(2);
+                let value = parts.join('');
+                value = (value.startsWith('=') ? value.slice(1) : value).trim();
+                value = value.length === 0 ? true : value;
+                try {
+                    value = JSON.parse(value.toString());
+                }
+                catch {
+                    // Keep original value if JSON parsing fails
+                }
+                // The option
+                pass2.push({
+                    arg: optionChar,
+                    isCommand: false,
+                    isOption: true,
+                    isShortOption: true,
+                    isLongOption: false,
+                    isValue: false,
+                    index: pass2.length,
+                    value,
+                });
+                // The value
+                pass2.push({
+                    arg: value.toString(),
+                    isCommand: false,
+                    isOption: false,
+                    isShortOption: false,
+                    isLongOption: false,
+                    isValue: true,
+                    index: pass2.length,
+                    value,
+                });
+            }
+            else if (token.isLongOption) {
+                const parts = token.arg.slice(2).split('=');
+                const optionName = parts[0] ?? '';
+                let value = parts.length > 1 ? parts.slice(1).join('=') : true;
+                if (typeof value === 'string') {
+                    try {
+                        value = JSON.parse(value);
+                    }
+                    catch {
+                        // Keep original value if JSON parsing fails
+                    }
+                }
+                // The option
+                pass2.push({
+                    arg: optionName,
+                    isCommand: false,
+                    isOption: true,
+                    isShortOption: false,
+                    isLongOption: true,
+                    isValue: false,
+                    index: pass2.length,
+                    value,
+                });
+                // The value
+                pass2.push({
+                    arg: value.toString(),
+                    isCommand: false,
+                    isOption: false,
+                    isShortOption: false,
+                    isLongOption: false,
+                    isValue: true,
+                    index: pass2.length,
+                    value,
+                });
+            }
+            else if (token.isValue) {
+                let processedArg = token.arg;
+                if (processedArg.startsWith('=')) {
+                    const parts = processedArg.split('=');
+                    processedArg = parts.slice(1).join('=');
+                }
+                let value = processedArg;
+                try {
+                    value = JSON.parse(processedArg);
+                }
+                catch {
+                    // Keep original value if JSON parsing fails
+                }
+                pass2.push({
+                    ...token,
+                    arg: processedArg,
+                    value,
+                });
+            }
+            else {
+                pass2.push(token);
+            }
+        });
+        const pass3 = [];
+        pass2.forEach((token, index) => {
+            if (token.isCommand) {
+                const lowerCaseArg = token.arg.toLowerCase();
+                pass3.push({
+                    ...token,
+                    arg: lowerCaseArg,
+                    value: lowerCaseArg,
+                });
+            }
+            else if (token.isOption) {
+                const nextToken = pass2[index + 1];
+                const nextNextToken = pass2[index + 2];
+                const peekIsValue1 = nextToken?.isValue ?? false;
+                const peekIsValue2 = nextNextToken?.isValue ?? false;
+                const value1 = nextToken?.value;
+                if (peekIsValue1 && peekIsValue2 && value1 === true && nextNextToken) {
+                    pass3.push({
+                        ...token,
+                        value: nextNextToken.value,
+                    });
+                }
+                else if (peekIsValue1 && nextToken) {
+                    pass3.push({
+                        ...token,
+                        value: nextToken.value,
+                    });
+                }
+                else {
+                    pass3.push(token);
+                }
+            }
+        });
+        return pass3;
+    }
+    /**
+     * @protected
+     * @memberof CommandLineParser
+     */
+    prepare() {
+        this.interpreter = process.argv[0] ?? '';
+        this.script = path.resolve(process.argv[1] ?? '');
+        const { name } = path.parse(this.script);
+        this.scriptName = this.config.name || name;
+    }
+    /**
+     * @protected
+     * @param {string} command
+     * @param {ICommandOption} option
+     * @param {any} value
+     * @memberof CommandLineParser
+     */
+    setOptionValue(command, option, value) {
+        if (!this.optionValues[command]) {
+            this.optionValues[command] = {};
+        }
+        if (option.multiple && value !== undefined) {
+            if (!Array.isArray(this.optionValues[command][option.name])) {
+                this.optionValues[command][option.name] = [];
+            }
+            this.optionValues[command][option.name].push(value);
+        }
+        else {
+            this.optionValues[command][option.name] = value;
+        }
+    }
+    /**
+     * @protected
+     * @param {IToken[]} options
+     * @return {object}
+     * @memberof CommandLineParser
+     */
+    validate(options) {
+        const commandToken = options.find(o => o.isCommand);
+        const errors = [];
+        const command = this.commands.find(c => c.name === commandToken?.arg) || this.commands.find(c => c.default);
+        if (!command) {
+            errors.push('No command provided!');
+            return { errors };
+        }
+        const tokenOptions = options.filter(o => o.isOption);
+        const commandOptions = command.options ?? [];
+        for (const option of commandOptions) {
+            const foundTokens = tokenOptions.filter(o => o.arg === option.name || o.arg === option.short);
+            if (option.required && foundTokens.length === 0 && option.default === undefined) {
+                errors.push(`Missing required option [${option.name}]`);
+            }
+            // Handle default values when no token is found
+            if (foundTokens.length === 0 && option.default !== undefined) {
+                const defaultValue = option.default;
+                // Type validation for default value
+                if (option.type === 'string' && !isString(defaultValue)) {
+                    errors.push(`Invalid default value for option [${option.name}], required ${option.type}, provided [${defaultValue}]`);
+                }
+                else if (option.type === 'number' && !isNumeric(defaultValue)) {
+                    errors.push(`Invalid default value for option [${option.name}], required ${option.type}, provided [${defaultValue}]`);
+                }
+                else if (option.type === 'boolean' && !isBoolean(defaultValue)) {
+                    errors.push(`Invalid default value for option [${option.name}], required ${option.type}, provided [${defaultValue}]`);
+                }
+                else if (option.type === 'email') {
+                    if (!isString(defaultValue)) {
+                        errors.push(`Invalid default value for option [${option.name}], required email string, provided [${defaultValue}]`);
+                    }
+                    else if (!isValidEmail(defaultValue)) {
+                        errors.push(`Invalid email default value for option [${option.name}]: ${getEmailValidationError(defaultValue)}`);
+                    }
+                }
+                else if (option.type === 'domain') {
+                    if (!isString(defaultValue)) {
+                        errors.push(`Invalid default value for option [${option.name}], required domain string, provided [${defaultValue}]`);
+                    }
+                    else if (!isValidDomain(defaultValue)) {
+                        errors.push(`Invalid domain default value for option [${option.name}]: ${getDomainValidationError(defaultValue)}`);
+                    }
+                }
+                // Custom validator validation for default value
+                if (option.validator && defaultValue !== undefined) {
+                    const validationResult = option.validator(defaultValue);
+                    if (validationResult !== true) {
+                        const errorMsg = typeof validationResult === 'string'
+                            ? validationResult
+                            : `Invalid default value for option [${option.name}]`;
+                        errors.push(errorMsg);
+                    }
+                }
+                this.setOptionValue(command.name, option, defaultValue);
+            }
+            for (const foundToken of foundTokens) {
+                const tokenValue = foundToken?.value ?? option.default;
+                if (tokenValue !== undefined) {
+                    // Type validation
+                    if (option.type === 'string' && !isString(tokenValue)) {
+                        errors.push(`Invalid value provided for option [${option.name}], required ${option.type}, provided [${tokenValue}]`);
+                    }
+                    else if (option.type === 'number' && !isNumeric(tokenValue)) {
+                        errors.push(`Invalid value provided for option [${option.name}], required ${option.type}, provided [${tokenValue}]`);
+                    }
+                    else if (option.type === 'boolean' && !isBoolean(tokenValue)) {
+                        errors.push(`Invalid value provided for option [${option.name}], required ${option.type}, provided [${tokenValue}]`);
+                    }
+                    else if (option.type === 'email') {
+                        if (!isString(tokenValue)) {
+                            errors.push(`Invalid value provided for option [${option.name}], required email string, provided [${tokenValue}]`);
+                        }
+                        else if (!isValidEmail(tokenValue)) {
+                            errors.push(`Invalid email provided for option [${option.name}]: ${getEmailValidationError(tokenValue)}`);
+                        }
+                    }
+                    else if (option.type === 'domain') {
+                        if (!isString(tokenValue)) {
+                            errors.push(`Invalid value provided for option [${option.name}], required domain string, provided [${tokenValue}]`);
+                        }
+                        else if (!isValidDomain(tokenValue)) {
+                            errors.push(`Invalid domain provided for option [${option.name}]: ${getDomainValidationError(tokenValue)}`);
+                        }
+                    }
+                    // Choices validation
+                    let choicesValid = true;
+                    if (option.choices && option.choices.length > 0 && tokenValue !== undefined) {
+                        if (!option.choices.includes(tokenValue)) {
+                            const choicesList = option.choices.map(c => `'${c}'`).join(', ');
+                            errors.push(`Invalid value '${tokenValue}' for option [${option.name}]. Must be one of: ${choicesList}`);
+                            choicesValid = false;
+                        }
+                    }
+                    // Custom validator validation (only if choices validation passed)
+                    if (choicesValid && option.validator && tokenValue !== undefined) {
+                        const validationResult = option.validator(tokenValue);
+                        if (validationResult !== true) {
+                            const errorMsg = typeof validationResult === 'string'
+                                ? validationResult
+                                : `Invalid value for option [${option.name}]`;
+                            errors.push(errorMsg);
+                        }
+                    }
+                }
+                this.setOptionValue(command.name, option, tokenValue);
+            }
+        }
+        return { errors, command };
+    }
+    /**
+     * @protected
+     * @param {ICommand | undefined} command
+     * @param {string[]} errors
+     * @param {boolean} isHelp
+     * @memberof CommandLineParser
+     */
+    help(command, errors, isHelp) {
+        console.log(`Welcome to ${this.scriptName} ${this.config.version}`);
+        if (!isHelp) {
+            const errorTable = [];
+            if (errors.length !== 0) {
+                console.log(command ? `\nErrors: (${command.name} command)\n` : '\nError:\n');
+                errors.forEach(l => errorTable.push(['\t', `- ${l}`]));
+            }
+            this.print(errorTable);
+        }
+        if (!command) {
+            console.log(this.commands.length !== 0 ? '\nCommands:\n' : '');
+            const commandTable = [];
+            this.commands.forEach(cmd => {
+                commandTable.push([
+                    '\t',
+                    cmd.name || '(default)',
+                    '\t\t',
+                    cmd.description || '',
+                    cmd.default ? `[default command]` : '',
+                ]);
+            });
+            this.print(commandTable);
+        }
+        else {
+            let table = [];
+            console.log('\nCommand:\n');
+            table.push([
+                '\t',
+                command.name,
+                '\t\t',
+                command.description || '',
+                '\t',
+                command.default ? `[default command]` : '',
+            ]);
+            this.print(table);
+            table = [];
+            console.log(`\nOptions:\n`);
+            const commandOptions = command.options ?? [];
+            commandOptions.forEach(option => {
+                table.push([
+                    '\t',
+                    `--${option.name}`,
+                    option.short ? ` | -${option.short}` : '',
+                    '\t\t',
+                    option.description || 'No description!',
+                    '\t',
+                    option.required ? '[required]' : '',
+                    option.multiple ? '[multiple]' : '',
+                    option.default !== undefined ? `[default:${option.default}]` : '',
+                    `[${option.type || 'string'}]`,
+                ]);
+            });
+            this.print(table);
+        }
+    }
+    /**
+     * Execute the command line parser
+     * @param {any} [context]
+     * @return {Promise<any>}
+     * @memberof CommandLineParser
+     */
+    async execute(context) {
+        if (this.commands.length > 1) {
+            this.commands.forEach(c => {
+                c.default = false;
+            });
+        }
+        try {
+            const options = this.parseTokens();
+            const { errors, command } = this.validate(options);
+            if (!command) {
+                this.help(undefined, errors, false);
+                return Promise.resolve();
+            }
+            const commandOptions = this.optionValues[command.name] ?? {};
+            const isHelp = commandOptions['help'] !== undefined;
+            if (errors.length !== 0 || isHelp) {
+                this.help(command, errors, isHelp);
+                return Promise.resolve();
+            }
+            try {
+                this.currentCommand = command;
+                commandOptions['showHelp'] = () => {
+                    this.help(this.currentCommand, [], true);
+                };
+                return await command.handler({ ...commandOptions, context });
+            }
+            catch (error) {
+                // Handler errors should be propagated
+                throw error;
+            }
+        }
+        catch (error) {
+            // Handle parsing errors gracefully by showing help
+            if (error instanceof MalformedArgumentError) {
+                this.help(undefined, [error.message], false);
+                return Promise.resolve();
+            }
+            // Re-throw other errors
+            throw error;
+        }
+    }
+    /**
+     * Validates command configuration for circular dependencies and conflicts
+     * @protected
+     * @param {ICommand} command
+     * @memberof CommandLineParser
+     */
+    validateCommandConfiguration(command) {
+        // Validate command name
+        if (!command.name || typeof command.name !== 'string') {
+            throw new InvalidConfigurationError('command.name', 'Command name is required and must be a string');
+        }
+        // Check for reserved command names
+        if (['help', 'version'].includes(command.name.toLowerCase())) {
+            throw new InvalidConfigurationError('command.name', `Command name '${command.name}' is reserved`);
+        }
+        // Validate command name format (no special characters except hyphens and underscores)
+        if (!/^[a-zA-Z][a-zA-Z0-9_-]*$/.test(command.name)) {
+            throw new InvalidConfigurationError('command.name', 'Command name must start with a letter and contain only letters, numbers, hyphens, and underscores');
+        }
+        // Check for duplicate command names
+        if (this.commands.some(existingCmd => existingCmd.name === command.name.toLowerCase())) {
+            throw new InvalidConfigurationError('command.name', `Command '${command.name}' already exists`);
+        }
+        // Validate options if present
+        if (command.options) {
+            this.validateOptionsConfiguration(command.options, command.name);
+        }
+    }
+    /**
+     * Validates options configuration for conflicts and format
+     * @protected
+     * @param {ICommandOption[]} options
+     * @param {string} commandName
+     * @memberof CommandLineParser
+     */
+    validateOptionsConfiguration(options, commandName) {
+        const optionNames = new Set();
+        const shortNames = new Set();
+        for (const option of options) {
+            // Validate option name
+            if (!option.name || typeof option.name !== 'string') {
+                throw new InvalidConfigurationError(`${commandName}.options`, 'Option name is required and must be a string');
+            }
+            // Check for reserved option names
+            if (['help', 'version'].includes(option.name.toLowerCase())) {
+                throw new InvalidConfigurationError(`${commandName}.options.${option.name}`, `Option name '${option.name}' is reserved`);
+            }
+            // Validate option name format
+            if (!/^[a-zA-Z][a-zA-Z0-9_-]*$/.test(option.name)) {
+                throw new InvalidConfigurationError(`${commandName}.options.${option.name}`, 'Option name must start with a letter and contain only letters, numbers, hyphens, and underscores');
+            }
+            // Check for duplicate option names
+            if (optionNames.has(option.name)) {
+                throw new InvalidConfigurationError(`${commandName}.options.${option.name}`, `Duplicate option name '${option.name}'`);
+            }
+            optionNames.add(option.name);
+            // Validate short name if present
+            if (option.short) {
+                if (typeof option.short !== 'string' || option.short.length !== 1) {
+                    throw new InvalidConfigurationError(`${commandName}.options.${option.name}.short`, 'Short option must be a single character');
+                }
+                if (!/^[a-zA-Z]$/.test(option.short)) {
+                    throw new InvalidConfigurationError(`${commandName}.options.${option.name}.short`, 'Short option must be a letter');
+                }
+                if (shortNames.has(option.short)) {
+                    throw new InvalidConfigurationError(`${commandName}.options.${option.name}.short`, `Duplicate short option '${option.short}'`);
+                }
+                shortNames.add(option.short);
+            }
+            // Validate conflicts and dependencies
+            if (option.conflicts && option.depends) {
+                const conflictSet = new Set(option.conflicts);
+                const dependsSet = new Set(option.depends);
+                const intersection = [...conflictSet].filter(x => dependsSet.has(x));
+                if (intersection.length > 0) {
+                    throw new InvalidConfigurationError(`${commandName}.options.${option.name}`, `Option cannot both conflict with and depend on: ${intersection.join(', ')}`);
+                }
+            }
+            // Validate choices if present
+            if (option.choices && (!Array.isArray(option.choices) || option.choices.length === 0)) {
+                throw new InvalidConfigurationError(`${commandName}.options.${option.name}.choices`, 'Choices must be a non-empty array');
+            }
+            // Validate default value against choices
+            if (option.choices &&
+                option.default !== undefined &&
+                !option.choices.includes(option.default)) {
+                throw new InvalidConfigurationError(`${commandName}.options.${option.name}.default`, `Default value '${option.default}' is not in choices`);
+            }
+        }
+    }
+    /**
+     * Add a command to the parser
+     * @param {ICommand} config
+     * @return {CommandLineParser}
+     * @memberof CommandLineParser
+     */
+    addCommand(config) {
+        const commandConfig = { ...config };
+        commandConfig.name = commandConfig.name.toLowerCase();
+        commandConfig.options = commandConfig.options ?? [];
+        // Validate command configuration
+        this.validateCommandConfiguration(commandConfig);
+        this.optionValues[commandConfig.name] = {};
+        if (this.config.skipHelp !== true) {
+            commandConfig.options.push({
+                name: 'help',
+                short: 'h',
+                type: 'boolean',
+                description: `Prints help and instructions for the ${commandConfig.name} command.`,
+            });
+        }
+        commandConfig.options.forEach(option => {
+            this.optionValues[commandConfig.name][option.name] = option.multiple ? [] : undefined;
+        });
+        this.commands.push(commandConfig);
+        return this;
+    }
+}
+//# sourceMappingURL=cmdline.js.map