expensify-common 2.0.187 → 2.0.189

package/dist/esm/CLI.js

@@ -0,0 +1,244 @@
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+/**
+ * This file contains a CLI utility class which can be used to declaratively implement a strongly-typed CLI.
+ * You provide a CLIConfig defining your arguments, then the class will handle parsing argv, type validation, error handling, and help messages.
+ */
+import * as readline from 'readline';
+import SafeString from './SafeString.js';
+class CLI {
+    constructor(config) {
+        var _a, _b, _c, _d, _e, _f;
+        this.config = config;
+        const rawArgs = process.argv.slice(2);
+        // Initialize all flags to false by default (including built-in flags)
+        this.flags = Object.assign(Object.assign({}, Object.fromEntries(Object.keys((_a = config.flags) !== null && _a !== void 0 ? _a : {}).map((key) => [key, false]))), { yes: false, no: false, help: false });
+        try {
+            const parsedNamedArgs = {};
+            const parsedPositionalArgs = {};
+            const providedNamedArgs = new Set();
+            let positionalIndex = 0;
+            for (let i = 0; i < rawArgs.length; i++) {
+                const rawArg = rawArgs.at(i);
+                if (rawArg === undefined) {
+                    continue;
+                }
+                if (rawArg.startsWith('--')) {
+                    // Either a flag or a named param
+                    const [rawArgName, rawArgValue] = rawArg.slice(2).split('=');
+                    if (rawArgName in this.flags) {
+                        // Arg is a flag
+                        this.flags[rawArgName] = true;
+                    }
+                    else if (config.namedArgs && rawArgName in config.namedArgs) {
+                        // Arg is a named arg
+                        providedNamedArgs.add(rawArgName);
+                        // Grab the value from the split token, otherwise go for the next token
+                        let argValueBeforeParse = '';
+                        if (rawArgValue) {
+                            argValueBeforeParse = rawArgValue;
+                        }
+                        else {
+                            argValueBeforeParse = (_b = rawArgs.at(++i)) !== null && _b !== void 0 ? _b : '';
+                            if (!argValueBeforeParse || argValueBeforeParse.startsWith('--')) {
+                                throw new Error(`Missing value for --${rawArgName}`);
+                            }
+                        }
+                        const spec = config.namedArgs[rawArgName];
+                        parsedNamedArgs[rawArgName] = CLI.parseStringArg(argValueBeforeParse, rawArgName, spec);
+                    }
+                    else {
+                        console.error(`Unknown flag: --${rawArgName}`);
+                        process.exit(1);
+                    }
+                }
+                else {
+                    // Arg is a positional arg
+                    const spec = (_c = config.positionalArgs) === null || _c === void 0 ? void 0 : _c.at(positionalIndex);
+                    if (spec === undefined) {
+                        throw new Error(`Unexpected arg: ${rawArg}`);
+                    }
+                    if (spec.variadic) {
+                        // Variadic: collect this and all remaining non-flag args into an array
+                        const collected = [];
+                        for (let j = i; j < rawArgs.length; j++) {
+                            const remaining = rawArgs.at(j);
+                            if (remaining === undefined || remaining.startsWith('--')) {
+                                break;
+                            }
+                            collected.push(remaining);
+                        }
+                        parsedPositionalArgs[spec.name] = collected;
+                        break;
+                    }
+                    parsedPositionalArgs[spec.name] = CLI.parseStringArg(rawArg, spec.name, spec);
+                    positionalIndex++;
+                }
+            }
+            // Handle help command
+            if (this.flags.help) {
+                this.printHelp();
+                process.exit(0);
+            }
+            // Handle supersession logic
+            const supersededArgs = new Set();
+            for (const [name, spec] of Object.entries((_d = config.namedArgs) !== null && _d !== void 0 ? _d : {})) {
+                if (providedNamedArgs.has(name) && spec.supersedes) {
+                    for (const supersededArg of spec.supersedes) {
+                        supersededArgs.add(supersededArg);
+                        if (providedNamedArgs.has(supersededArg)) {
+                            console.warn(`⚠️  Warning: --${supersededArg} is superseded by --${name} and will be ignored.`);
+                        }
+                    }
+                }
+            }
+            // Validate that all required args are present, assign defaults where values are not parsed
+            for (const [name, spec] of Object.entries((_e = config.namedArgs) !== null && _e !== void 0 ? _e : {})) {
+                if (name in parsedNamedArgs) {
+                    if (supersededArgs.has(name)) {
+                        parsedNamedArgs[name] = undefined;
+                    }
+                }
+                else if (supersededArgs.has(name)) {
+                    // This arg was superseded, so don't require it and don't assign a default
+                    continue;
+                }
+                else if (spec.default !== undefined) {
+                    parsedNamedArgs[name] = spec.default;
+                }
+                else if (spec.required === false) {
+                    // Explicitly marked as optional, leave undefined
+                    continue;
+                }
+                else {
+                    // Arguments without defaults are required by default (unless explicitly marked as optional)
+                    throw new Error(`Missing required named argument --${name}`);
+                }
+            }
+            for (const spec of (_f = config.positionalArgs) !== null && _f !== void 0 ? _f : []) {
+                if (!(spec.name in parsedPositionalArgs)) {
+                    if (spec.default !== undefined) {
+                        parsedPositionalArgs[spec.name] = spec.default;
+                    }
+                    else if (spec.variadic) {
+                        parsedPositionalArgs[spec.name] = [];
+                    }
+                    else {
+                        throw new Error(`Missing required positional argument --${spec.name}`);
+                    }
+                }
+            }
+            this.namedArgs = parsedNamedArgs;
+            this.positionalArgs = parsedPositionalArgs;
+        }
+        catch (err) {
+            // If help flag was set, the error is from process.exit(0) in tests (where it's mocked to throw) - just rethrow it
+            if (this.flags.help) {
+                throw err;
+            }
+            if (err instanceof Error) {
+                console.error(err.message);
+                this.printHelp();
+            }
+            else {
+                console.error('An unexpected error occurred initializing the CLI.');
+            }
+            process.exit(1);
+        }
+    }
+    printHelp() {
+        var _a;
+        const { flags = {}, namedArgs = {}, positionalArgs = [] } = this.config;
+        const scriptName = (_a = process.argv.at(1)) !== null && _a !== void 0 ? _a : 'script.ts';
+        const positionalUsage = positionalArgs
+            .map((arg) => {
+            const label = arg.variadic ? `${arg.name}...` : arg.name;
+            return arg.default === undefined ? `<${label}>` : `[${label}]`;
+        })
+            .join(' ');
+        const namedArgUsage = Object.keys(namedArgs)
+            .map((key) => `[--${key} <value>]`)
+            .join(' ');
+        const flagUsage = [...Object.keys(flags), '--yes', '--no', '--help'].map((key) => `[${key.startsWith('--') ? key : `--${key}`}]`).join(' ');
+        console.log(`\nUsage: npx ts-node ${scriptName} ${flagUsage} ${namedArgUsage} ${positionalUsage}\n`);
+        console.log('Flags:');
+        for (const [name, spec] of Object.entries(flags)) {
+            console.log(`  --${name.padEnd(20)} ${spec.description}`);
+        }
+        // Built-in flags
+        console.log(`  --${'yes'.padEnd(20)} Automatically answer "yes" to all confirmation prompts.`);
+        console.log(`  --${'no'.padEnd(20)} Automatically answer "no" to all confirmation prompts.`);
+        console.log(`  --${'help'.padEnd(20)} Show this help message.`);
+        console.log('');
+        if (Object.keys(namedArgs).length > 0) {
+            console.log('Named Arguments:');
+            for (const [name, spec] of Object.entries(namedArgs)) {
+                const defaultLabel = spec.default !== undefined ? ` (default: ${SafeString(spec.default)})` : '';
+                const supersededLabel = spec.supersedes && spec.supersedes.length > 0 ? ` (supersedes: ${spec.supersedes.join(', ')})` : '';
+                console.log(`  --${name.padEnd(20)} ${spec.description}${defaultLabel}${supersededLabel}`);
+            }
+            console.log('');
+        }
+        if (positionalArgs.length > 0) {
+            console.log('Positional Arguments:');
+            for (const arg of positionalArgs) {
+                const defaultLabel = arg.default !== undefined ? ` (default: ${SafeString(arg.default)})` : '';
+                console.log(`  ${arg.name.padEnd(22)} ${arg.description}${defaultLabel}`);
+            }
+            console.log('');
+        }
+    }
+    static parseStringArg(rawString, paramName, spec) {
+        if ('parse' in spec && !!spec.parse) {
+            try {
+                return spec.parse(rawString);
+            }
+            catch (error) {
+                let errorMessage = '';
+                if (error instanceof Error) {
+                    errorMessage = error.message;
+                }
+                console.error(`Invalid value for --${paramName}: ${errorMessage}`);
+                process.exit(1);
+            }
+        }
+        else {
+            return rawString;
+        }
+    }
+    /**
+     * Prompts the user for confirmation and returns true if they confirm (y/yes), false otherwise.
+     * If --yes flag was passed, returns true immediately without prompting.
+     * If --no flag was passed, returns false immediately without prompting.
+     */
+    promptUserConfirmation(message) {
+        return __awaiter(this, void 0, void 0, function* () {
+            // Check for built-in flags first
+            if (this.flags.yes) {
+                return true;
+            }
+            if (this.flags.no) {
+                return false;
+            }
+            const rl = readline.createInterface({
+                input: process.stdin,
+                output: process.stdout,
+            });
+            return new Promise((resolve) => {
+                rl.question(message, (answer) => {
+                    rl.close();
+                    const normalizedAnswer = answer.trim().toLowerCase();
+                    resolve(normalizedAnswer === 'y' || normalizedAnswer === 'yes');
+                });
+            });
+        });
+    }
+}
+export default CLI;