@oclif/core 1.14.2 → 1.16.1

package/CHANGELOG.md

@@ -2,6 +2,27 @@
 
 All notable changes to this project will be documented in this file. See [standard-version](https://github.com/conventional-changelog/standard-version) for commit guidelines.
 
+### [1.16.1](https://github.com/oclif/core/compare/v1.16.0...v1.16.1) (2022-09-08)
+
+
+### Bug Fixes
+
+* support environment variables for boolean flags ([#488](https://github.com/oclif/core/issues/488)) ([#490](https://github.com/oclif/core/issues/490)) ([506945c](https://github.com/oclif/core/commit/506945c6ea2f8b75f0d56ad1f6e62a3717384a42)), closes [#487](https://github.com/oclif/core/issues/487)
+
+## [1.16.0](https://github.com/oclif/core/compare/v1.15.0...v1.16.0) (2022-08-24)
+
+
+### Features
+
+* support complex flag relationships ([#468](https://github.com/oclif/core/issues/468)) ([222d1f6](https://github.com/oclif/core/commit/222d1f67012557ac0707077d6c8840966dbf00cb))
+
+## [1.15.0](https://github.com/oclif/core/compare/v1.14.2...v1.15.0) (2022-08-23)
+
+
+### Features
+
+* add InferredFlags type ([#473](https://github.com/oclif/core/issues/473)) ([ee5ce65](https://github.com/oclif/core/commit/ee5ce651899c0ef586d425567ef3b78468dca627))
+
 ### [1.14.2](https://github.com/oclif/core/compare/v1.14.1...v1.14.2) (2022-08-18)
 
 

package/lib/config/config.js

@@ -660,6 +660,7 @@ async function toCached(c, plugin) {
                 multiple: flag.multiple,
                 options: flag.options,
                 dependsOn: flag.dependsOn,
+                relationships: flag.relationships,
                 exclusive: flag.exclusive,
                 default: await defaultToCached(flag),
             };

package/lib/flags.d.ts

@@ -1,19 +1,13 @@
-import { OptionFlag, Definition, BooleanFlag, EnumFlagOptions, Default } from './interfaces';
-export declare function build<T>(defaults: {
-    parse: OptionFlag<T>['parse'];
-} & Partial<OptionFlag<T>>): Definition<T>;
-export declare function build(defaults: Partial<OptionFlag<string>>): Definition<string>;
-export declare function option<T>(options: {
-    parse: OptionFlag<T>['parse'];
-} & Partial<OptionFlag<T>>): OptionFlag<T | undefined>;
-export declare function _enum<T = string>(opts: EnumFlagOptions<T> & {
+import { OptionFlag, BooleanFlag, EnumFlagOptions, Default } from './interfaces';
+export { boolean, integer, url, directory, file, string, build, option, custom } from './parser';
+export declare function _enum<T = string>(opts: EnumFlagOptions<T, true> & {
     multiple: true;
 } & ({
     required: true;
 } | {
-    default: Default<T>;
+    default: Default<T[]>;
 })): OptionFlag<T[]>;
-export declare function _enum<T = string>(opts: EnumFlagOptions<T> & {
+export declare function _enum<T = string>(opts: EnumFlagOptions<T, true> & {
     multiple: true;
 }): OptionFlag<T[] | undefined>;
 export declare function _enum<T = string>(opts: EnumFlagOptions<T> & ({
@@ -23,8 +17,5 @@ export declare function _enum<T = string>(opts: EnumFlagOptions<T> & ({
 })): OptionFlag<T>;
 export declare function _enum<T = string>(opts: EnumFlagOptions<T>): OptionFlag<T | undefined>;
 export { _enum as enum };
-declare const stringFlag: Definition<string>;
-export { stringFlag as string };
-export { boolean, integer, url, directory, file } from './parser';
 export declare const version: (opts?: Partial<BooleanFlag<boolean>>) => BooleanFlag<void>;
 export declare const help: (opts?: Partial<BooleanFlag<boolean>>) => BooleanFlag<void>;

package/lib/flags.js

@@ -1,17 +1,19 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.help = exports.version = exports.file = exports.directory = exports.url = exports.integer = exports.boolean = exports.string = exports.enum = exports._enum = exports.option = exports.build = void 0;
-const Parser = require("./parser");
-function build(defaults) {
-    return Parser.flags.build(defaults);
-}
-exports.build = build;
-function option(options) {
-    return build(options)();
-}
-exports.option = option;
+exports.help = exports.version = exports.enum = exports._enum = exports.custom = exports.option = exports.build = exports.string = exports.file = exports.directory = exports.url = exports.integer = exports.boolean = void 0;
+const parser_1 = require("./parser");
+var parser_2 = require("./parser");
+Object.defineProperty(exports, "boolean", { enumerable: true, get: function () { return parser_2.boolean; } });
+Object.defineProperty(exports, "integer", { enumerable: true, get: function () { return parser_2.integer; } });
+Object.defineProperty(exports, "url", { enumerable: true, get: function () { return parser_2.url; } });
+Object.defineProperty(exports, "directory", { enumerable: true, get: function () { return parser_2.directory; } });
+Object.defineProperty(exports, "file", { enumerable: true, get: function () { return parser_2.file; } });
+Object.defineProperty(exports, "string", { enumerable: true, get: function () { return parser_2.string; } });
+Object.defineProperty(exports, "build", { enumerable: true, get: function () { return parser_2.build; } });
+Object.defineProperty(exports, "option", { enumerable: true, get: function () { return parser_2.option; } });
+Object.defineProperty(exports, "custom", { enumerable: true, get: function () { return parser_2.custom; } });
 function _enum(opts) {
-    return build({
+    return (0, parser_1.custom)({
         async parse(input) {
             if (!opts.options.includes(input))
                 throw new Error(`Expected --${this.name}=${input} to be one of: ${opts.options.join(', ')}`);
@@ -23,16 +25,8 @@ function _enum(opts) {
 }
 exports._enum = _enum;
 exports.enum = _enum;
-const stringFlag = build({});
-exports.string = stringFlag;
-var parser_1 = require("./parser");
-Object.defineProperty(exports, "boolean", { enumerable: true, get: function () { return parser_1.boolean; } });
-Object.defineProperty(exports, "integer", { enumerable: true, get: function () { return parser_1.integer; } });
-Object.defineProperty(exports, "url", { enumerable: true, get: function () { return parser_1.url; } });
-Object.defineProperty(exports, "directory", { enumerable: true, get: function () { return parser_1.directory; } });
-Object.defineProperty(exports, "file", { enumerable: true, get: function () { return parser_1.file; } });
 const version = (opts = {}) => {
-    return Parser.flags.boolean({
+    return (0, parser_1.boolean)({
         description: 'Show CLI version.',
         ...opts,
         parse: async (_, cmd) => {
@@ -43,7 +37,7 @@ const version = (opts = {}) => {
 };
 exports.version = version;
 const help = (opts = {}) => {
-    return Parser.flags.boolean({
+    return (0, parser_1.boolean)({
         description: 'Show CLI help.',
         ...opts,
         parse: async (_, cmd) => {

package/lib/interfaces/flags.d.ts

@@ -0,0 +1,34 @@
+import { FlagInput } from './parser';
+/**
+ * Infer the flags that are returned by Command.parse. This is useful for when you want to assign the flags as a class property.
+ *
+ * @example
+ * export type StatusFlags = Interfaces.InferredFlags<typeof Status.flags & typeof Status.globalFlags>
+ *
+ * export abstract class BaseCommand extends Command {
+ *   static enableJsonFlag = true
+ *
+ *   static globalFlags = {
+ *     config: Flags.string({
+ *       description: 'specify config file',
+ *     }),
+ *   }
+ * }
+ *
+ * export default class Status extends BaseCommand {
+ *   static flags = {
+ *     force: Flags.boolean({char: 'f', description: 'a flag'}),
+ *   }
+ *
+ *   public flags!: StatusFlags
+ *
+ *   public async run(): Promise<StatusFlags> {
+ *     const result = await this.parse(Status)
+ *     this.flags = result.flags
+ *     return result.flags
+ *   }
+ * }
+ */
+export declare type InferredFlags<T> = T extends FlagInput<infer F> ? F & {
+    json: boolean | undefined;
+} : unknown;

package/lib/interfaces/flags.js

@@ -1 +1,2 @@
 "use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/lib/interfaces/index.d.ts

@@ -11,3 +11,4 @@ export { PJSON } from './pjson';
 export { Plugin, PluginOptions, Options } from './plugin';
 export { Topic } from './topic';
 export { TSConfig } from './ts-config';
+export { InferredFlags } from './flags';

package/lib/interfaces/parser.d.ts

@@ -78,14 +78,20 @@ declare type MetadataFlag = {
 };
 export declare type ListItem = [string, string | undefined];
 export declare type List = ListItem[];
-export declare type DefaultContext<T> = {
-    options: OptionFlag<T>;
-    flags: {
-        [k: string]: string;
-    };
+export declare type DefaultContext<T, P> = {
+    options: P & OptionFlag<T>;
+    flags: Record<string, string>;
+};
+export declare type Default<T, P = Record<string, unknown>> = T | ((context: DefaultContext<T, P>) => Promise<T>);
+export declare type DefaultHelp<T, P = Record<string, unknown>> = T | ((context: DefaultContext<T, P>) => Promise<string | undefined>);
+export declare type FlagRelationship = string | {
+    name: string;
+    when: (flags: Record<string, unknown>) => Promise<boolean>;
+};
+export declare type Relationship = {
+    type: 'all' | 'some' | 'none';
+    flags: FlagRelationship[];
 };
-export declare type Default<T> = T | ((context: DefaultContext<T>) => Promise<T>);
-export declare type DefaultHelp<T> = T | ((context: DefaultContext<T>) => Promise<string | undefined>);
 export declare type FlagProps = {
     name: string;
     char?: AlphabetLowercase | AlphabetUppercase;
@@ -109,10 +115,34 @@ export declare type FlagProps = {
      * Shows this flag in a separate list in the help.
      */
     helpGroup?: string;
+    /**
+     * Accept an environment variable as input
+     */
+    env?: string;
+    /**
+     * If true, the flag will not be shown in the help.
+     */
     hidden?: boolean;
+    /**
+     * If true, the flag will be required.
+     */
     required?: boolean;
+    /**
+     * List of flags that this flag depends on.
+     */
     dependsOn?: string[];
+    /**
+     * List of flags that cannot be used with this flag.
+     */
     exclusive?: string[];
+    /**
+     * Exactly one of these flags must be provided.
+     */
+    exactlyOne?: string[];
+    /**
+     * Define complex relationships between flags.
+     */
+    relationships?: Relationship[];
 };
 export declare type BooleanFlagProps = FlagProps & {
     type: 'boolean';
@@ -122,48 +152,60 @@ export declare type OptionFlagProps = FlagProps & {
     type: 'option';
     helpValue?: string;
     options?: string[];
-    multiple: boolean;
+    multiple?: boolean;
 };
-export declare type FlagBase<T, I> = FlagProps & {
-    exactlyOne?: string[];
-    /**
-     * also accept an environment variable as input
-     */
-    env?: string;
-    parse(input: I, context: any): Promise<T>;
+export declare type FlagParser<T, I, P = any> = (input: I, context: any, opts: P & OptionFlag<T>) => Promise<T>;
+export declare type FlagBase<T, I, P = any> = FlagProps & {
+    parse: FlagParser<T, I, P>;
 };
 export declare type BooleanFlag<T> = FlagBase<T, boolean> & BooleanFlagProps & {
     /**
-     * specifying a default of false is the same not specifying a default
+     * specifying a default of false is the same as not specifying a default
      */
     default?: Default<boolean>;
 };
-export declare type OptionFlag<T> = FlagBase<T, string> & OptionFlagProps & {
-    default?: Default<T | undefined>;
+export declare type CustomOptionFlag<T, P = any, M = false> = FlagBase<T, string, P> & OptionFlagProps & {
     defaultHelp?: DefaultHelp<T>;
     input: string[];
+    default?: M extends true ? Default<T[] | undefined, P> : Default<T | undefined, P>;
 };
-export declare type Definition<T> = {
-    (options: {
+export declare type OptionFlag<T> = FlagBase<T, string> & OptionFlagProps & {
+    defaultHelp?: DefaultHelp<T>;
+    input: string[];
+} & ({
+    default?: Default<T | undefined>;
+    multiple: false;
+} | {
+    default?: Default<T[] | undefined>;
+    multiple: true;
+});
+export declare type Definition<T, P = Record<string, unknown>> = {
+    (options: P & {
         multiple: true;
     } & ({
         required: true;
     } | {
-        default: Default<T>;
+        default: Default<T[]>;
     }) & Partial<OptionFlag<T>>): OptionFlag<T[]>;
-    (options: {
+    (options: P & {
         multiple: true;
-    } & Partial<OptionFlag<T[]>>): OptionFlag<T[] | undefined>;
-    (options: ({
+    } & Partial<OptionFlag<T>>): OptionFlag<T[] | undefined>;
+    (options: P & ({
         required: true;
     } | {
         default: Default<T>;
     }) & Partial<OptionFlag<T>>): OptionFlag<T>;
-    (options?: Partial<OptionFlag<T>>): OptionFlag<T | undefined>;
+    (options?: P & Partial<OptionFlag<T>>): OptionFlag<T | undefined>;
 };
-export declare type EnumFlagOptions<T> = Partial<OptionFlag<T>> & {
+export declare type EnumFlagOptions<T, M = false> = Partial<CustomOptionFlag<T, any, M>> & {
     options: T[];
-};
+} & ({
+    default?: Default<T | undefined>;
+    multiple?: false;
+} | {
+    default?: Default<T[] | undefined>;
+    multiple: true;
+});
 export declare type Flag<T> = BooleanFlag<T> | OptionFlag<T>;
 export declare type Input<TFlags extends FlagOutput, GFlags extends FlagOutput> = {
     flags?: FlagInput<TFlags>;

package/lib/parser/errors.d.ts

@@ -1,6 +1,12 @@
 import { CLIError } from '../errors';
 import { ParserArg, CLIParseErrorOptions, OptionFlag, Flag } from '../interfaces';
 export { CLIError } from '../errors';
+export declare type Validation = {
+    name: string;
+    status: 'success' | 'failed';
+    validationFn: string;
+    reason?: string;
+};
 export declare class CLIParseError extends CLIError {
     parse: CLIParseErrorOptions['parse'];
     constructor(options: CLIParseErrorOptions & {
@@ -37,3 +43,8 @@ export declare class FlagInvalidOptionError extends CLIParseError {
 export declare class ArgInvalidOptionError extends CLIParseError {
     constructor(arg: ParserArg<any>, input: string);
 }
+export declare class FailedFlagValidationError extends CLIParseError {
+    constructor({ parse, failed }: CLIParseErrorOptions & {
+        failed: Validation[];
+    });
+}

package/lib/parser/errors.js

@@ -1,8 +1,9 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ArgInvalidOptionError = exports.FlagInvalidOptionError = exports.UnexpectedArgsError = exports.RequiredFlagError = exports.RequiredArgsError = exports.InvalidArgsSpecError = exports.CLIParseError = exports.CLIError = void 0;
+exports.FailedFlagValidationError = exports.ArgInvalidOptionError = exports.FlagInvalidOptionError = exports.UnexpectedArgsError = exports.RequiredFlagError = exports.RequiredArgsError = exports.InvalidArgsSpecError = exports.CLIParseError = exports.CLIError = void 0;
 const errors_1 = require("../errors");
 const deps_1 = require("./deps");
+const util_1 = require("../config/util");
 var errors_2 = require("../errors");
 Object.defineProperty(exports, "CLIError", { enumerable: true, get: function () { return errors_2.CLIError; } });
 // eslint-disable-next-line new-cap
@@ -10,7 +11,8 @@ const m = (0, deps_1.default)()
     // eslint-disable-next-line node/no-missing-require
     .add('help', () => require('./help'))
     // eslint-disable-next-line node/no-missing-require
-    .add('list', () => require('./list'));
+    .add('list', () => require('./list'))
+    .add('chalk', () => require('chalk'));
 class CLIParseError extends errors_1.CLIError {
     constructor(options) {
         options.message += '\nSee more help with --help';
@@ -76,3 +78,13 @@ class ArgInvalidOptionError extends CLIParseError {
     }
 }
 exports.ArgInvalidOptionError = ArgInvalidOptionError;
+class FailedFlagValidationError extends CLIParseError {
+    constructor({ parse, failed }) {
+        const reasons = failed.map(r => r.reason);
+        const deduped = (0, util_1.uniq)(reasons);
+        const errString = deduped.length === 1 ? 'error' : 'errors';
+        const message = `The following ${errString} occurred:\n  ${m.chalk.dim(deduped.join('\n  '))}`;
+        super({ parse, message });
+    }
+}
+exports.FailedFlagValidationError = FailedFlagValidationError;

package/lib/parser/flags.d.ts

@@ -1,96 +1,59 @@
 /// <reference types="node" />
 import { URL } from 'url';
-import { Definition, OptionFlag, BooleanFlag, Default } from '../interfaces';
+import { Definition, OptionFlag, BooleanFlag } from '../interfaces';
+import { FlagParser, CustomOptionFlag } from '../interfaces/parser';
+/**
+ * Create a custom flag.
+ *
+ * @example
+ * type Id = string
+ * type IdOpts = { startsWith: string; length: number };
+ *
+ * export const myFlag = custom<Id, IdOpts>({
+ *   parse: async (input, opts) => {
+ *     if (input.startsWith(opts.startsWith) && input.length === opts.length) {
+ *       return input
+ *     }
+ *
+ *     throw new Error('Invalid id')
+ *   },
+ * })
+ */
+export declare function custom<T, P = Record<string, unknown>>(defaults: {
+    parse: FlagParser<T, string, P>;
+    multiple: true;
+} & Partial<CustomOptionFlag<T, P, true>>): Definition<T, P>;
+export declare function custom<T, P = Record<string, unknown>>(defaults: {
+    parse: FlagParser<T, string, P>;
+} & Partial<CustomOptionFlag<T, P>>): Definition<T, P>;
+export declare function custom<T = string, P = Record<string, unknown>>(defaults: Partial<CustomOptionFlag<T, P>>): Definition<T, P>;
+/**
+ * @deprecated Use Flags.custom instead.
+ */
 export declare function build<T>(defaults: {
     parse: OptionFlag<T>['parse'];
 } & Partial<OptionFlag<T>>): Definition<T>;
 export declare function build(defaults: Partial<OptionFlag<string>>): Definition<string>;
 export declare function boolean<T = boolean>(options?: Partial<BooleanFlag<T>>): BooleanFlag<T>;
-export declare function integer(opts: Partial<OptionFlag<number>> & {
-    min?: number;
-    max?: number;
-} & {
-    multiple: true;
-} & ({
-    required: true;
-} | {
-    default: Default<number>;
-})): OptionFlag<number[]>;
-export declare function integer(opts: Partial<OptionFlag<number>> & {
-    min?: number;
-    max?: number;
-} & {
-    multiple: true;
-}): OptionFlag<number[] | undefined>;
-export declare function integer(opts: Partial<OptionFlag<number>> & {
-    min?: number;
-    max?: number;
-} & ({
-    required: true;
-} | {
-    default: Default<number>;
-})): OptionFlag<number>;
-export declare function integer(opts?: Partial<OptionFlag<number>> & {
-    min?: number;
-    max?: number;
-}): OptionFlag<number | undefined>;
-export declare function directory(opts: Partial<OptionFlag<string>> & {
-    exists?: boolean;
-} & {
-    multiple: true;
-} & ({
-    required: true;
-} | {
-    default: Default<string>;
-})): OptionFlag<string[]>;
-export declare function directory(opts: Partial<OptionFlag<string>> & {
-    exists?: boolean;
-} & {
-    multiple: true;
-}): OptionFlag<string[] | undefined>;
-export declare function directory(opts: {
-    exists?: boolean;
-} & Partial<OptionFlag<string>> & ({
-    required: true;
-} | {
-    default: Default<string>;
-})): OptionFlag<string>;
-export declare function directory(opts?: {
-    exists?: boolean;
-} & Partial<OptionFlag<string>>): OptionFlag<string | undefined>;
-export declare function file(opts: Partial<OptionFlag<string>> & {
-    exists?: boolean;
-} & {
-    multiple: true;
-} & ({
-    required: true;
-} | {
-    default: Default<string>;
-})): OptionFlag<string[]>;
-export declare function file(opts: Partial<OptionFlag<string>> & {
-    exists?: boolean;
-} & {
-    multiple: true;
-}): OptionFlag<string[] | undefined>;
-export declare function file(opts: {
-    exists?: boolean;
-} & Partial<OptionFlag<string>> & ({
-    required: true;
-} | {
-    default: Default<string>;
-})): OptionFlag<string>;
-export declare function file(opts?: {
-    exists?: boolean;
-} & Partial<OptionFlag<string>>): OptionFlag<string | undefined>;
+export declare const integer: Definition<number, {
+    min?: number | undefined;
+    max?: number | undefined;
+}>;
+export declare const directory: Definition<string, {
+    exists?: boolean | undefined;
+}>;
+export declare const file: Definition<string, {
+    exists?: boolean | undefined;
+}>;
 /**
  * Initializes a string as a URL. Throws an error
  * if the string is not a valid URL.
  */
-export declare const url: Definition<URL>;
+export declare const url: Definition<URL, Record<string, unknown>>;
 export declare function option<T>(options: {
     parse: OptionFlag<T>['parse'];
-} & Partial<OptionFlag<T>>): OptionFlag<T | undefined>;
-declare const stringFlag: Definition<string>;
+} & Partial<CustomOptionFlag<T>>): OptionFlag<T | undefined>;
+declare const stringFlag: Definition<string, Record<string, unknown>>;
 export { stringFlag as string };
 export declare const defaultFlags: {
     color: BooleanFlag<boolean>;

package/lib/parser/flags.js

@@ -1,13 +1,25 @@
 "use strict";
-// tslint:disable interface-over-type-literal
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.defaultFlags = exports.string = exports.option = exports.url = exports.file = exports.directory = exports.integer = exports.boolean = exports.build = void 0;
+exports.defaultFlags = exports.string = exports.option = exports.url = exports.file = exports.directory = exports.integer = exports.boolean = exports.build = exports.custom = void 0;
 const url_1 = require("url");
 const fs = require("fs");
+function custom(defaults) {
+    return (options = {}) => {
+        return {
+            parse: async (i, _context, _opts) => i,
+            ...defaults,
+            ...options,
+            input: [],
+            multiple: Boolean(options.multiple === undefined ? defaults.multiple : options.multiple),
+            type: 'option',
+        };
+    };
+}
+exports.custom = custom;
 function build(defaults) {
     return (options = {}) => {
         return {
-            parse: async (i, _) => i,
+            parse: async (i, _context) => i,
             ...defaults,
             ...options,
             input: [],
@@ -26,53 +38,37 @@ function boolean(options = {}) {
     };
 }
 exports.boolean = boolean;
-function integer(opts = {}) {
-    return build({
-        ...opts,
-        parse: async (input) => {
-            if (!/^-?\d+$/.test(input))
-                throw new Error(`Expected an integer but received: ${input}`);
-            const num = Number.parseInt(input, 10);
-            if (opts.min !== undefined && num < opts.min)
-                throw new Error(`Expected an integer greater than or equal to ${opts.min} but received: ${input}`);
-            if (opts.max !== undefined && num > opts.max)
-                throw new Error(`Expected an integer less than or equal to ${opts.max} but received: ${input}`);
-            return opts.parse ? opts.parse(input, 1) : num;
-        },
-    })();
-}
-exports.integer = integer;
-function directory(opts = {}) {
-    return build({
-        ...opts,
-        parse: async (input) => {
-            if (opts.exists) {
-                // 2nd "context" arg is required but unused
-                return opts.parse ? opts.parse(await dirExists(input), true) : dirExists(input);
-            }
-            return opts.parse ? opts.parse(input, true) : input;
-        },
-    })();
-}
-exports.directory = directory;
-function file(opts = {}) {
-    return build({
-        ...opts,
-        parse: async (input) => {
-            if (opts.exists) {
-                // 2nd "context" arg is required but unused
-                return opts.parse ? opts.parse(await fileExists(input), true) : fileExists(input);
-            }
-            return opts.parse ? opts.parse(input, true) : input;
-        },
-    })();
-}
-exports.file = file;
+exports.integer = custom({
+    parse: async (input, _, opts) => {
+        if (!/^-?\d+$/.test(input))
+            throw new Error(`Expected an integer but received: ${input}`);
+        const num = Number.parseInt(input, 10);
+        if (opts.min !== undefined && num < opts.min)
+            throw new Error(`Expected an integer greater than or equal to ${opts.min} but received: ${input}`);
+        if (opts.max !== undefined && num > opts.max)
+            throw new Error(`Expected an integer less than or equal to ${opts.max} but received: ${input}`);
+        return num;
+    },
+});
+exports.directory = custom({
+    parse: async (input, _, opts) => {
+        if (opts.exists)
+            return dirExists(input);
+        return input;
+    },
+});
+exports.file = custom({
+    parse: async (input, _, opts) => {
+        if (opts.exists)
+            return fileExists(input);
+        return input;
+    },
+});
 /**
  * Initializes a string as a URL. Throws an error
  * if the string is not a valid URL.
  */
-exports.url = build({
+exports.url = custom({
     parse: async (input) => {
         try {
             return new url_1.URL(input);
@@ -83,10 +79,10 @@ exports.url = build({
     },
 });
 function option(options) {
-    return build(options)();
+    return custom(options)();
 }
 exports.option = option;
-const stringFlag = build({});
+const stringFlag = custom({});
 exports.string = stringFlag;
 exports.defaultFlags = {
     color: boolean({ allowNo: true }),

package/lib/parser/index.d.ts

@@ -1,4 +1,3 @@
-/// <reference types="node" />
 import * as args from './args';
 import * as flags from './flags';
 import { Input, ParserOutput } from '../interfaces';
@@ -8,5 +7,4 @@ export { flagUsages } from './help';
 export declare function parse<TFlags, GFlags, TArgs extends {
     [name: string]: string;
 }>(argv: string[], options: Input<TFlags, GFlags>): Promise<ParserOutput<TFlags, GFlags, TArgs>>;
-declare const boolean: typeof flags.boolean, integer: typeof flags.integer, url: import("../interfaces").Definition<import("url").URL>, directory: typeof flags.directory, file: typeof flags.file;
-export { boolean, integer, url, directory, file };
+export { boolean, integer, url, directory, file, string, build, option, custom } from './flags';

package/lib/parser/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.file = exports.directory = exports.url = exports.integer = exports.boolean = exports.parse = exports.flagUsages = exports.flags = exports.args = void 0;
+exports.custom = exports.option = exports.build = exports.string = exports.file = exports.directory = exports.url = exports.integer = exports.boolean = exports.parse = exports.flagUsages = exports.flags = exports.args = void 0;
 const args = require("./args");
 exports.args = args;
 const deps_1 = require("./deps");
@@ -27,13 +27,17 @@ async function parse(argv, options) {
     };
     const parser = new parse_1.Parser(input);
     const output = await parser.parse();
-    m.validate({ input, output });
+    await m.validate({ input, output });
     return output;
 }
 exports.parse = parse;
-const { boolean, integer, url, directory, file } = flags;
-exports.boolean = boolean;
-exports.integer = integer;
-exports.url = url;
-exports.directory = directory;
-exports.file = file;
+var flags_1 = require("./flags");
+Object.defineProperty(exports, "boolean", { enumerable: true, get: function () { return flags_1.boolean; } });
+Object.defineProperty(exports, "integer", { enumerable: true, get: function () { return flags_1.integer; } });
+Object.defineProperty(exports, "url", { enumerable: true, get: function () { return flags_1.url; } });
+Object.defineProperty(exports, "directory", { enumerable: true, get: function () { return flags_1.directory; } });
+Object.defineProperty(exports, "file", { enumerable: true, get: function () { return flags_1.file; } });
+Object.defineProperty(exports, "string", { enumerable: true, get: function () { return flags_1.string; } });
+Object.defineProperty(exports, "build", { enumerable: true, get: function () { return flags_1.build; } });
+Object.defineProperty(exports, "option", { enumerable: true, get: function () { return flags_1.option; } });
+Object.defineProperty(exports, "custom", { enumerable: true, get: function () { return flags_1.custom; } });

package/lib/parser/parse.js

@@ -149,13 +149,13 @@ class Parser {
                     flags[token.flag] = true;
                 }
                 // eslint-disable-next-line no-await-in-loop
-                flags[token.flag] = await flag.parse(flags[token.flag], this.context);
+                flags[token.flag] = await flag.parse(flags[token.flag], this.context, flag);
             }
             else {
                 const input = token.input;
                 this._validateOptions(flag, input);
                 // eslint-disable-next-line no-await-in-loop
-                const value = flag.parse ? await flag.parse(input, this.context) : input;
+                const value = flag.parse ? await flag.parse(input, this.context, flag) : input;
                 if (flag.multiple) {
                     flags[token.flag] = flags[token.flag] || [];
                     flags[token.flag].push(value);
@@ -169,12 +169,18 @@ class Parser {
             const flag = this.input.flags[k];
             if (flags[k])
                 continue;
-            if (flag.type === 'option' && flag.env) {
+            if (flag.env) {
                 const input = process.env[flag.env];
-                if (input) {
-                    this._validateOptions(flag, input);
-                    // eslint-disable-next-line no-await-in-loop
-                    flags[k] = await flag.parse(input, this.context);
+                if (flag.type === 'option') {
+                    if (input) {
+                        this._validateOptions(flag, input);
+                        // eslint-disable-next-line no-await-in-loop
+                        flags[k] = await flag.parse(input, this.context, flag);
+                    }
+                }
+                else if (flag.type === 'boolean') {
+                    // eslint-disable-next-line no-negated-condition
+                    flags[k] = input !== undefined ? ['true', 'TRUE', '1', 'yes', 'YES', 'y', 'Y'].includes(input) : false;
                 }
             }
             if (!(k in flags) && flag.default !== undefined) {

package/lib/parser/validate.d.ts

@@ -2,4 +2,4 @@ import { ParserInput, ParserOutput } from '../interfaces';
 export declare function validate(parse: {
     input: ParserInput;
     output: ParserOutput;
-}): void;
+}): Promise<void>;

package/lib/parser/validate.js

@@ -1,14 +1,14 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.validate = void 0;
-const errors_1 = require("../errors");
-const errors_2 = require("./errors");
-function validate(parse) {
+const errors_1 = require("./errors");
+const util_1 = require("../config/util");
+async function validate(parse) {
     function validateArgs() {
         const maxArgs = parse.input.args.length;
         if (parse.input.strict && parse.output.argv.length > maxArgs) {
             const extras = parse.output.argv.slice(maxArgs);
-            throw new errors_2.UnexpectedArgsError({ parse, args: extras });
+            throw new errors_1.UnexpectedArgsError({ parse, args: extras });
         }
         const missingRequiredArgs = [];
         let hasOptional = false;
@@ -19,63 +19,138 @@ function validate(parse) {
             else if (hasOptional) {
                 // (required arg) check whether an optional has occurred before
                 // optionals should follow required, not before
-                throw new errors_2.InvalidArgsSpecError({ parse, args: parse.input.args });
+                throw new errors_1.InvalidArgsSpecError({ parse, args: parse.input.args });
             }
             if (arg.required && !parse.output.argv[index] && parse.output.argv[index] !== 0) {
                 missingRequiredArgs.push(arg);
             }
         }
         if (missingRequiredArgs.length > 0) {
-            throw new errors_2.RequiredArgsError({ parse, args: missingRequiredArgs });
+            throw new errors_1.RequiredArgsError({ parse, args: missingRequiredArgs });
         }
     }
+    async function validateFlags() {
+        const promises = Object.entries(parse.input.flags).map(async ([name, flag]) => {
+            const results = [];
+            if (parse.output.flags[name] !== undefined) {
+                results.push(...await validateRelationships(name, flag), await validateDependsOn(name, flag.dependsOn ?? []), await validateExclusive(name, flag.exclusive ?? []), await validateExactlyOne(name, flag.exactlyOne ?? []));
+            }
+            else if (flag.required) {
+                results.push({ status: 'failed', name, validationFn: 'required', reason: `Missing required flag ${name}` });
+            }
+            else if (flag.exactlyOne && flag.exactlyOne.length > 0) {
+                results.push(validateAcrossFlags(flag));
+            }
+            return results;
+        });
+        const results = (await Promise.all(promises)).flat();
+        const failed = results.filter(r => r.status === 'failed');
+        if (failed.length > 0)
+            throw new errors_1.FailedFlagValidationError({ parse, failed });
+    }
+    async function resolveFlags(flags) {
+        const promises = flags.map(async (flag) => {
+            if (typeof flag === 'string') {
+                return [flag, parse.output.flags[flag]];
+            }
+            const result = await flag.when(parse.output.flags);
+            return result ? [flag.name, parse.output.flags[flag.name]] : null;
+        });
+        const resolved = await Promise.all(promises);
+        return Object.fromEntries(resolved.filter(r => r !== null));
+    }
+    function getPresentFlags(flags) {
+        return Object.keys(flags).reduce((acc, key) => {
+            if (flags[key])
+                acc.push(key);
+            return acc;
+        }, []);
+    }
     function validateAcrossFlags(flag) {
+        const base = { name: flag.name, validationFn: 'validateAcrossFlags' };
         const intersection = Object.entries(parse.input.flags)
             .map(entry => entry[0]) // array of flag names
             .filter(flagName => parse.output.flags[flagName] !== undefined) // with values
             .filter(flagName => flag.exactlyOne && flag.exactlyOne.includes(flagName)); // and in the exactlyOne list
         if (intersection.length === 0) {
             // the command's exactlyOne may or may not include itself, so we'll use Set to add + de-dupe
-            throw new errors_1.CLIError(`Exactly one of the following must be provided: ${[
-                ...new Set(flag.exactlyOne?.map(flag => `--${flag}`)),
-            ].join(', ')}`);
+            const deduped = (0, util_1.uniq)(flag.exactlyOne?.map(flag => `--${flag}`) ?? []).join(', ');
+            const reason = `Exactly one of the following must be provided: ${deduped}`;
+            return { ...base, status: 'failed', reason };
         }
+        return { ...base, status: 'success' };
     }
-    function validateFlags() {
-        for (const [name, flag] of Object.entries(parse.input.flags)) {
-            if (parse.output.flags[name] !== undefined) {
-                for (const also of flag.dependsOn || []) {
-                    if (!parse.output.flags[also]) {
-                        throw new errors_1.CLIError(`--${also}= must also be provided when using --${name}=`);
-                    }
-                }
-                for (const also of flag.exclusive || []) {
-                    // do not enforce exclusivity for flags that were defaulted
-                    if (parse.output.metadata.flags[also] &&
-                        parse.output.metadata.flags[also].setFromDefault)
-                        continue;
-                    if (parse.output.metadata.flags[name] &&
-                        parse.output.metadata.flags[name].setFromDefault)
-                        continue;
-                    if (parse.output.flags[also]) {
-                        throw new errors_1.CLIError(`--${also}= cannot also be provided when using --${name}=`);
-                    }
-                }
-                for (const also of flag.exactlyOne || []) {
-                    if (also !== name && parse.output.flags[also]) {
-                        throw new errors_1.CLIError(`--${also}= cannot also be provided when using --${name}=`);
-                    }
-                }
+    async function validateExclusive(name, flags) {
+        const base = { name, validationFn: 'validateExclusive' };
+        const resolved = await resolveFlags(flags);
+        const keys = getPresentFlags(resolved);
+        for (const flag of keys) {
+            // do not enforce exclusivity for flags that were defaulted
+            if (parse.output.metadata.flags && parse.output.metadata.flags[flag]?.setFromDefault)
+                continue;
+            if (parse.output.metadata.flags && parse.output.metadata.flags[name]?.setFromDefault)
+                continue;
+            if (parse.output.flags[flag]) {
+                return { ...base, status: 'failed', reason: `--${flag}=${parse.output.flags[flag]} cannot also be provided when using --${name}` };
             }
-            else if (flag.required) {
-                throw new errors_2.RequiredFlagError({ parse, flag });
-            }
-            else if (flag.exactlyOne && flag.exactlyOne.length > 0) {
-                validateAcrossFlags(flag);
+        }
+        return { ...base, status: 'success' };
+    }
+    async function validateExactlyOne(name, flags) {
+        const base = { name, validationFn: 'validateExactlyOne' };
+        const resolved = await resolveFlags(flags);
+        const keys = getPresentFlags(resolved);
+        for (const flag of keys) {
+            if (flag !== name && parse.output.flags[flag]) {
+                return { ...base, status: 'failed', reason: `--${flag} cannot also be provided when using --${name}` };
             }
         }
+        return { ...base, status: 'success' };
+    }
+    async function validateDependsOn(name, flags) {
+        const base = { name, validationFn: 'validateDependsOn' };
+        const resolved = await resolveFlags(flags);
+        const foundAll = Object.values(resolved).every(Boolean);
+        if (!foundAll) {
+            const formattedFlags = Object.keys(resolved).map(f => `--${f}`).join(', ');
+            return { ...base, status: 'failed', reason: `All of the following must be provided when using --${name}: ${formattedFlags}` };
+        }
+        return { ...base, status: 'success' };
+    }
+    async function validateSome(name, flags) {
+        const base = { name, validationFn: 'validateSome' };
+        const resolved = await resolveFlags(flags);
+        const foundAtLeastOne = Object.values(resolved).some(Boolean);
+        if (!foundAtLeastOne) {
+            const formattedFlags = Object.keys(resolved).map(f => `--${f}`).join(', ');
+            return { ...base, status: 'failed', reason: `One of the following must be provided when using --${name}: ${formattedFlags}` };
+        }
+        return { ...base, status: 'success' };
+    }
+    async function validateRelationships(name, flag) {
+        if (!flag.relationships)
+            return [];
+        const results = await Promise.all(flag.relationships.map(async (relationship) => {
+            const flags = relationship.flags ?? [];
+            const results = [];
+            switch (relationship.type) {
+                case 'all':
+                    results.push(await validateDependsOn(name, flags));
+                    break;
+                case 'some':
+                    results.push(await validateSome(name, flags));
+                    break;
+                case 'none':
+                    results.push(await validateExclusive(name, flags));
+                    break;
+                default:
+                    break;
+            }
+            return results;
+        }));
+        return results.flat();
     }
     validateArgs();
-    validateFlags();
+    await validateFlags();
 }
 exports.validate = validate;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@oclif/core",
   "description": "base library for oclif CLIs",
-  "version": "1.14.2",
+  "version": "1.16.1",
   "author": "Salesforce",
   "bugs": "https://github.com/oclif/core/issues",
   "dependencies": {
@@ -74,6 +74,7 @@
     "shx": "^0.3.4",
     "sinon": "^11.1.2",
     "ts-node": "^9.1.1",
+    "tsd": "^0.22.0",
     "typescript": "4.5.5"
   },
   "engines": {