@oclif/core 4.9.0 → 4.10.0

package/lib/help/command.js

@@ -57,8 +57,9 @@ class CommandHelp extends formatter_1.HelpFormatter {
         if (args.filter((a) => a.description).length === 0)
             return;
         return args.map((a) => {
-            // Add ellipsis to indicate that the argument takes multiple values if strict is false
-            let name = this.command.strict === false ? `${a.name.toUpperCase()}...` : a.name.toUpperCase();
+            // Add ellipsis for variadic args, or for all args when strict is false (backward compat)
+            const suffix = a.multiple ? '...' : this.command.strict === false ? '...' : '';
+            let name = `${a.name.toUpperCase()}${suffix}`;
             name = a.required ? `${name}` : `[${name}]`;
             let description = a.description || '';
             if (a.default)

package/lib/help/docopts.js

@@ -100,11 +100,12 @@ class DocOpts {
     toString() {
         const opts = ['<%= command.id %>'];
         if (this.cmd.args) {
-            // If strict is false, add ellipsis to indicate that the argument takes multiple values
-            const suffix = this.cmd.strict === false ? '...' : '';
             const a = Object.values((0, ensure_arg_object_1.ensureArgObject)(this.cmd.args))
                 .filter((arg) => !arg.hidden)
-                .map((arg) => arg.required ? `${arg.name.toUpperCase()}${suffix}` : `[${arg.name.toUpperCase()}${suffix}]`) || [];
+                .map((arg) => {
+                const suffix = arg.multiple ? '...' : this.cmd.strict === false ? '...' : '';
+                return arg.required ? `${arg.name.toUpperCase()}${suffix}` : `[${arg.name.toUpperCase()}${suffix}]`;
+            }) || [];
             opts.push(...a);
         }
         try {

package/lib/interfaces/parser.d.ts

@@ -192,6 +192,11 @@ export type ArgProps = {
      * If true, the flag will be required.
      */
     required?: boolean;
+    /**
+     * If true, the arg accepts multiple values. Only one arg per command can have multiple: true.
+     * All args after a variadic arg must be required.
+     */
+    multiple?: boolean;
     options?: string[];
     ignoreStdin?: boolean;
     /**
@@ -245,6 +250,20 @@ export type Arg<T, P = CustomOptions> = ArgProps & {
     parse: ArgParser<T, P>;
 };
 export type ArgDefinition<T, P = CustomOptions> = {
+    (options: P & {
+        multiple: true;
+    } & ({
+        required: true;
+    } | {
+        default: ArgDefault<T[]>;
+    }) & Omit<Partial<Arg<T, P>>, 'default'> & {
+        default?: ArgDefault<T[] | undefined>;
+    }): Arg<T[], P>;
+    (options: P & {
+        multiple: true;
+    } & Omit<Partial<Arg<T, P>>, 'default'> & {
+        default?: ArgDefault<T[] | undefined>;
+    }): Arg<T[] | undefined, P>;
     (options: P & ({
         required: true;
     } | {

package/lib/parser/errors.d.ts

@@ -16,8 +16,9 @@ export declare class CLIParseError extends CLIError {
 }
 export declare class InvalidArgsSpecError extends CLIParseError {
     args: ArgInput;
-    constructor({ args, exit, parse }: CLIParseErrorOptions & {
+    constructor({ args, exit, parse, reason }: CLIParseErrorOptions & {
         args: ArgInput;
+        reason?: string;
     });
 }
 export declare class RequiredArgsError extends CLIParseError {

package/lib/parser/errors.js

@@ -23,8 +23,11 @@ class CLIParseError extends errors_1.CLIError {
 exports.CLIParseError = CLIParseError;
 class InvalidArgsSpecError extends CLIParseError {
     args;
-    constructor({ args, exit, parse }) {
+    constructor({ args, exit, parse, reason }) {
         let message = 'Invalid argument spec';
+        if (reason) {
+            message += `: ${reason}`;
+        }
         const namedArgs = Object.values(args).filter((a) => a.name);
         if (namedArgs.length > 0) {
             const list = (0, list_1.default)(namedArgs.map((a) => [`${a.name} (${a.required ? 'required' : 'optional'})`, a.description]));

package/lib/parser/parse.js

@@ -201,43 +201,93 @@ class Parser {
         const tokens = this._argTokens;
         let stdinRead = false;
         const ctx = this.context;
-        for (const [name, arg] of Object.entries(this.input.args)) {
-            const token = tokens.find((t) => t.arg === name);
-            ctx.token = token;
-            if (token) {
-                if (arg.options && !arg.options.includes(token.input)) {
-                    throw new errors_1.ArgInvalidOptionError(arg, token.input);
-                }
-                const parsed = await arg.parse(token.input, ctx, arg);
-                argv.push(parsed);
-                args[token.arg] = parsed;
+        const parseArgInput = async (name, arg, input) => {
+            if (arg.options && !arg.options.includes(input)) {
+                throw new errors_1.ArgInvalidOptionError(arg, input);
             }
-            else if (!arg.ignoreStdin && !stdinRead) {
-                let stdin = await (0, exports.readStdin)();
-                if (stdin) {
-                    stdin = stdin.trim();
-                    const parsed = await arg.parse(stdin, ctx, arg);
-                    argv.push(parsed);
-                    args[name] = parsed;
-                }
-                stdinRead = true;
+            ctx.token = { arg: name, input, type: 'arg' };
+            const parsed = await arg.parse(input, ctx, arg);
+            argv.push(parsed);
+            args[name] = parsed;
+        };
+        const applyDefault = async (name, arg) => {
+            if (args[name] !== undefined)
+                return;
+            if (!arg.default && arg.default !== false)
+                return;
+            const value = typeof arg.default === 'function' ? await arg.default() : arg.default;
+            if (Array.isArray(value)) {
+                for (const v of value)
+                    argv.push(v);
+            }
+            else {
+                argv.push(value);
             }
-            if (!args[name] && (arg.default || arg.default === false)) {
-                if (typeof arg.default === 'function') {
-                    const f = await arg.default();
-                    argv.push(f);
-                    args[name] = f;
+            args[name] = value;
+        };
+        const tryStdin = async (name, arg) => {
+            if (arg.ignoreStdin || stdinRead)
+                return;
+            let stdin = await (0, exports.readStdin)();
+            stdinRead = true;
+            if (!stdin)
+                return;
+            stdin = stdin.trim();
+            await parseArgInput(name, arg, stdin);
+        };
+        const argEntries = Object.entries(this.input.args);
+        const variadicIndex = argEntries.findIndex(([, arg]) => arg.multiple);
+        if (variadicIndex === -1) {
+            for (const [name, arg] of argEntries) {
+                const token = tokens.find((t) => t.arg === name);
+                ctx.token = token;
+                await (token ? parseArgInput(name, arg, token.input) : tryStdin(name, arg));
+                await applyDefault(name, arg);
+            }
+            // Append unmatched tokens to argv (for strict: false)
+            for (const token of tokens) {
+                if (args[token.arg] !== undefined)
+                    continue;
+                argv.push(token.input);
+            }
+        }
+        else {
+            const tokenInputs = tokens.map((t) => t.input);
+            // Consume pre-variadic args from the front
+            for (let i = 0; i < variadicIndex; i++) {
+                const [name, arg] = argEntries[i];
+                const input = tokenInputs.shift();
+                await (input === undefined ? tryStdin(name, arg) : parseArgInput(name, arg, input));
+                await applyDefault(name, arg);
+            }
+            // Consume post-variadic args from the back
+            const postVariadicParsing = [];
+            for (let i = argEntries.length - 1; i > variadicIndex; i--) {
+                const [name, arg] = argEntries[i];
+                const input = tokenInputs.pop();
+                if (input !== undefined) {
+                    postVariadicParsing.unshift({ arg, input, name });
                 }
-                else {
-                    argv.push(arg.default);
-                    args[name] = arg.default;
+            }
+            // Everything remaining goes to the variadic arg
+            const [variadicName, variadicArg] = argEntries[variadicIndex];
+            if (tokenInputs.length > 0) {
+                const parsedValues = [];
+                for (const input of tokenInputs) {
+                    await parseArgInput(variadicName, variadicArg, input);
+                    parsedValues.push(args[variadicName]);
                 }
+                args[variadicName] = parsedValues;
+            }
+            for (const { arg, input, name } of postVariadicParsing) {
+                await parseArgInput(name, arg, input);
+            }
+            // Apply defaults for any args that didn't receive values
+            await applyDefault(variadicName, variadicArg);
+            for (let i = variadicIndex + 1; i < argEntries.length; i++) {
+                const [name, arg] = argEntries[i];
+                await applyDefault(name, arg);
             }
-        }
-        for (const token of tokens) {
-            if (args[token.arg] !== undefined)
-                continue;
-            argv.push(token.input);
         }
         return { args, argv };
     }

package/lib/parser/validate.js

@@ -6,6 +6,41 @@ const errors_1 = require("./errors");
 async function validate(parse) {
     let cachedResolvedFlags;
     function validateArgs() {
+        // Validate variadic arg constraints (definition-time checks)
+        const argEntries = Object.entries(parse.input.args);
+        const variadicIndex = argEntries.findIndex(([, arg]) => arg.multiple);
+        if (variadicIndex !== -1) {
+            // Only one variadic arg is allowed
+            const secondVariadic = argEntries.findIndex(([, arg], i) => i > variadicIndex && arg.multiple);
+            if (secondVariadic !== -1) {
+                throw new errors_1.InvalidArgsSpecError({
+                    args: parse.input.args,
+                    parse,
+                    reason: 'only one variadic arg (multiple: true) is allowed',
+                });
+            }
+            // All args before a variadic arg must be required (otherwise assignment is ambiguous)
+            for (let i = 0; i < variadicIndex; i++) {
+                if (!argEntries[i][1].required) {
+                    throw new errors_1.InvalidArgsSpecError({
+                        args: parse.input.args,
+                        parse,
+                        reason: `args before a variadic arg must be required, but "${argEntries[i][0]}" is optional`,
+                    });
+                }
+            }
+            // All args after a variadic arg must be required (otherwise assignment is ambiguous)
+            for (let i = variadicIndex + 1; i < argEntries.length; i++) {
+                if (!argEntries[i][1].required) {
+                    throw new errors_1.InvalidArgsSpecError({
+                        args: parse.input.args,
+                        parse,
+                        reason: `args after a variadic arg must be required, but "${argEntries[i][0]}" is optional`,
+                    });
+                }
+            }
+        }
+        const variadicArgFound = variadicIndex !== -1;
         if (parse.output.nonExistentFlags?.length > 0) {
             throw new errors_1.NonExistentFlagsError({
                 flags: parse.output.nonExistentFlags,
@@ -13,7 +48,8 @@ async function validate(parse) {
             });
         }
         const maxArgs = Object.keys(parse.input.args).length;
-        if (parse.input.strict && parse.output.argv.length > maxArgs) {
+        const hasVariadicArg = Object.values(parse.input.args).some((arg) => arg.multiple);
+        if (parse.input.strict && !hasVariadicArg && parse.output.argv.length > maxArgs) {
             const extras = parse.output.argv.slice(maxArgs);
             throw new errors_1.UnexpectedArgsError({
                 args: extras,
@@ -26,9 +62,11 @@ async function validate(parse) {
             if (!arg.required) {
                 hasOptional = true;
             }
-            else if (hasOptional) {
+            else if (hasOptional && !variadicArgFound) {
                 // (required arg) check whether an optional has occurred before
                 // optionals should follow required, not before
+                // Skip this check when a variadic arg is present, since the variadic
+                // validation above already enforces that args after a variadic are required
                 throw new errors_1.InvalidArgsSpecError({
                     args: parse.input.args,
                     parse,

package/lib/util/cache-command.js

@@ -60,6 +60,7 @@ async function cacheArgs(cmdArgs, respectNoCacheDefault) {
             default: await (0, cache_default_value_1.cacheDefaultValue)(arg, respectNoCacheDefault),
             description: arg.description,
             hidden: arg.hidden,
+            multiple: arg.multiple,
             name,
             noCacheDefault: arg.noCacheDefault,
             options: arg.options,

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@oclif/core",
   "description": "base library for oclif CLIs",
-  "version": "4.9.0",
+  "version": "4.10.0",
   "author": "Salesforce",
   "bugs": "https://github.com/oclif/core/issues",
   "dependencies": {