@oclif/core 3.0.0-beta.9 → 3.0.0

package/lib/interfaces/parser.d.ts

@@ -1,6 +1,5 @@
 import { Command } from '../command';
 import { AlphabetLowercase, AlphabetUppercase } from './alphabet';
-import { Config } from './config';
 export type FlagOutput = {
     [name: string]: any;
 };
@@ -155,15 +154,13 @@ export type FlagProps = {
      */
     aliases?: string[];
     /**
-     * Emit deprecation warning when a flag alias is provided
+     * Alternate short chars that can be used for this flag.
      */
-    deprecateAliases?: boolean;
+    charAliases?: (AlphabetLowercase | AlphabetUppercase)[];
     /**
-     * Delimiter to separate the values for a multiple value flag.
-     * Only respected if multiple is set to true. Default behavior is to
-     * separate on spaces.
+     * Emit deprecation warning when a flag alias is provided
      */
-    delimiter?: ',';
+    deprecateAliases?: boolean;
     /**
      * If true, the value returned by defaultHelp will not be cached in the oclif.manifest.json.
      * This is helpful if the default value contains sensitive data that shouldn't be published to npm.
@@ -201,13 +198,19 @@ export type BooleanFlagProps = FlagProps & {
 export type OptionFlagProps = FlagProps & {
     type: 'option';
     helpValue?: string;
-    options?: string[];
+    options?: readonly string[];
     multiple?: boolean;
+    /**
+     * Delimiter to separate the values for a multiple value flag.
+     * Only respected if multiple is set to true. Default behavior is to
+     * separate on spaces.
+     */
+    delimiter?: ',';
 };
 export type FlagParserContext = Command & {
     token: FlagToken;
 };
-export type FlagParser<T, I extends string | boolean, P = CustomOptions> = (input: I, context: FlagParserContext, opts: P & OptionFlag<T, P>) => Promise<T>;
+export type FlagParser<T, I extends string | boolean, P = CustomOptions> = (input: I, context: FlagParserContext, opts: P & OptionFlag<T, P>) => T extends Array<infer U> ? Promise<U | undefined> : Promise<T | undefined>;
 export type ArgParserContext = Command & {
     token: ArgToken;
 };
@@ -234,45 +237,185 @@ export type BooleanFlag<T> = FlagProps & BooleanFlagProps & {
     default?: FlagDefault<boolean>;
     parse: (input: boolean, context: FlagParserContext, opts: FlagProps & BooleanFlagProps) => Promise<T>;
 };
-export type OptionFlagDefaults<T, P = CustomOptions, M = false> = FlagProps & OptionFlagProps & {
-    parse: FlagParser<T, string, P>;
-    defaultHelp?: FlagDefaultHelp<T>;
-    input: string[];
-    default?: M extends true ? FlagDefault<T[] | undefined, P> : FlagDefault<T | undefined, P>;
-};
 export type OptionFlag<T, P = CustomOptions> = FlagProps & OptionFlagProps & {
-    parse: FlagParser<T, string, P>;
+    parse: FlagParser<T | undefined, string, P>;
     defaultHelp?: FlagDefaultHelp<T, P>;
     input: string[];
-} & ({
     default?: FlagDefault<T | undefined, P>;
+};
+type ReturnTypeSwitches = {
+    multiple: boolean;
+    requiredOrDefaulted: boolean;
+};
+/**
+ * The logic here is as follows:
+ * - If requiredOrDefaulted is true && multiple is true, then the return type is T[]
+ *    - It's possible that T extends an Array, if so we want to return T so that the return isn't T[][]
+ * - If requiredOrDefaulted is true && multiple is false, then the return type is T
+ * - If requiredOrDefaulted is false && multiple is true, then the return type is T[] | undefined
+ *    - It's possible that T extends an Array, if so we want to return T so that the return isn't T[][]
+ * - If requiredOrDefaulted is false && multiple is false, then the return type is T | undefined
+ */
+type FlagReturnType<T, R extends ReturnTypeSwitches> = R['requiredOrDefaulted'] extends true ? R['multiple'] extends true ? [T] extends [Array<unknown>] ? T : T[] : T : R['multiple'] extends true ? [T] extends [Array<unknown>] ? T | undefined : T[] | undefined : T | undefined;
+/**
+ * FlagDefinition types a function that takes `options` and returns an OptionFlag<T>.
+ *
+ * This is returned by `Flags.custom()` and `Flags.option()`, which each take a `defaults` object
+ * that mirrors the OptionFlag interface.
+ *
+ * The `T` in the `OptionFlag<T>` return type is determined by a combination of the provided defaults for
+ * `multiple`, `required`, and `default` and the provided options for those same properties. If these properties
+ * are provided in the options, they override the defaults.
+ *
+ * no options or defaults -> T | undefined
+ * `required` -> T
+ * `default` -> T
+ * `multiple` -> T[] | undefined
+ * `required` + `multiple` -> T[]
+ * `default` + `multiple` -> T[]
+ */
+export type FlagDefinition<T, P = CustomOptions, R extends ReturnTypeSwitches = {
     multiple: false;
-} | {
-    default?: FlagDefault<T[] | undefined, P>;
-    multiple: true;
-});
-export type FlagDefinition<T, P = CustomOptions> = {
+    requiredOrDefaulted: false;
+}> = {
+    (options: P & {
+        multiple: false;
+        required: true;
+    } & Partial<OptionFlag<FlagReturnType<T, {
+        multiple: false;
+        requiredOrDefaulted: true;
+    }>, P>>): OptionFlag<FlagReturnType<T, {
+        multiple: false;
+        requiredOrDefaulted: true;
+    }>>;
     (options: P & {
         multiple: true;
+        required: false;
+    } & Partial<OptionFlag<FlagReturnType<T, {
+        multiple: true;
+        requiredOrDefaulted: false;
+    }>, P>>): OptionFlag<FlagReturnType<T, {
+        multiple: true;
+        requiredOrDefaulted: false;
+    }>>;
+    (options: P & {
+        multiple: false;
+        required: false;
+    } & Partial<OptionFlag<FlagReturnType<T, {
+        multiple: false;
+        requiredOrDefaulted: false;
+    }>, P>>): OptionFlag<FlagReturnType<T, {
+        multiple: false;
+        requiredOrDefaulted: false;
+    }>>;
+    (options: R['multiple'] extends true ? // `multiple` is defaulted to true and either `required=true` or `default` are provided in options
+    P & ({
+        required: true;
+    } | {
+        default: OptionFlag<FlagReturnType<T, {
+            multiple: R['multiple'];
+            requiredOrDefaulted: true;
+        }>, P>['default'];
+    }) & Partial<OptionFlag<FlagReturnType<T, {
+        multiple: R['multiple'];
+        requiredOrDefaulted: true;
+    }>, P>> : // `multiple` is NOT defaulted to true and either `required=true` or `default` are provided in options
+    P & {
+        multiple?: false | undefined;
     } & ({
         required: true;
     } | {
-        default: FlagDefault<T[]>;
-    }) & Partial<OptionFlag<T, P>>): OptionFlag<T[]>;
-    (options: P & {
+        default: OptionFlag<FlagReturnType<T, {
+            multiple: R['multiple'];
+            requiredOrDefaulted: true;
+        }>, P>['default'];
+    }) & Partial<OptionFlag<FlagReturnType<T, {
+        multiple: R['multiple'];
+        requiredOrDefaulted: true;
+    }>, P>>): OptionFlag<FlagReturnType<T, {
+        multiple: R['multiple'];
+        requiredOrDefaulted: true;
+    }>>;
+    (options: R['multiple'] extends true ? // `multiple` is defaulted to true and either `required=true` or `default` are provided in options
+    P & ({
+        required: true;
+    } | {
+        default: OptionFlag<FlagReturnType<T, {
+            multiple: true;
+            requiredOrDefaulted: true;
+        }>, P>['default'];
+    }) & Partial<OptionFlag<FlagReturnType<T, {
         multiple: true;
-    } & Partial<OptionFlag<T>>): OptionFlag<T[] | undefined>;
-    (options: P & ({
+        requiredOrDefaulted: true;
+    }>, P>> : // `multiple` is NOT defaulted to true but `multiple=true` and either `required=true` or `default` are provided in options
+    P & {
+        multiple: true;
+    } & ({
+        required: true;
+    } | {
+        default: OptionFlag<FlagReturnType<T, {
+            multiple: true;
+            requiredOrDefaulted: true;
+        }>, P>['default'];
+    }) & Partial<OptionFlag<FlagReturnType<T, {
+        multiple: true;
+        requiredOrDefaulted: true;
+    }>, P>>): OptionFlag<FlagReturnType<T, {
+        multiple: true;
+        requiredOrDefaulted: true;
+    }>>;
+    (options: P & {
+        multiple?: false | undefined;
+    } & ({
         required: true;
     } | {
-        default: FlagDefault<T>;
-    }) & Partial<OptionFlag<T>>): OptionFlag<T>;
-    (options?: P & Partial<OptionFlag<T>>): OptionFlag<T | undefined>;
+        default: OptionFlag<FlagReturnType<T, {
+            multiple: R['multiple'];
+            requiredOrDefaulted: true;
+        }>, P>['default'];
+    }) & Partial<OptionFlag<FlagReturnType<T, {
+        multiple: R['multiple'];
+        requiredOrDefaulted: true;
+    }>, P>>): OptionFlag<FlagReturnType<T, {
+        multiple: R['multiple'];
+        requiredOrDefaulted: true;
+    }>>;
+    (options: P & {
+        required: false;
+    } & Partial<OptionFlag<FlagReturnType<T, {
+        multiple: R['multiple'];
+        requiredOrDefaulted: false;
+    }>, P>>): OptionFlag<FlagReturnType<T, {
+        multiple: R['multiple'];
+        requiredOrDefaulted: false;
+    }>>;
+    (options: P & {
+        multiple: false;
+    } & Partial<OptionFlag<FlagReturnType<T, {
+        multiple: false;
+        requiredOrDefaulted: R['requiredOrDefaulted'];
+    }>, P>>): OptionFlag<FlagReturnType<T, {
+        multiple: false;
+        requiredOrDefaulted: R['requiredOrDefaulted'];
+    }>>;
+    (options?: P & {
+        multiple?: false | undefined;
+    } & Partial<OptionFlag<FlagReturnType<T, R>, P>>): OptionFlag<FlagReturnType<T, R>>;
+    (options: P & {
+        multiple: true;
+    } & Partial<OptionFlag<FlagReturnType<T, {
+        multiple: true;
+        requiredOrDefaulted: R['requiredOrDefaulted'];
+    }>, P>>): OptionFlag<FlagReturnType<T, {
+        multiple: true;
+        requiredOrDefaulted: R['requiredOrDefaulted'];
+    }>>;
 };
 export type Flag<T> = BooleanFlag<T> | OptionFlag<T>;
 export type Input<TFlags extends FlagOutput, BFlags extends FlagOutput, AFlags extends ArgOutput> = {
     flags?: FlagInput<TFlags>;
     baseFlags?: FlagInput<BFlags>;
+    enableJsonFlag?: true | false;
     args?: ArgInput<AFlags>;
     strict?: boolean;
     context?: ParserContext;
@@ -289,33 +432,14 @@ export type ParserInput = {
 export type ParserContext = Command & {
     token?: FlagToken | ArgToken;
 };
-export type CompletionContext = {
-    args?: {
-        [name: string]: string;
-    };
-    flags?: {
-        [name: string]: string;
-    };
-    argv?: string[];
-    config: Config;
-};
-export type Completion = {
-    skipCache?: boolean;
-    cacheDuration?: number;
-    cacheKey?(ctx: CompletionContext): Promise<string>;
-    options(ctx: CompletionContext): Promise<string[]>;
-};
-export type CompletableOptionFlag<T> = OptionFlag<T> & {
-    completion?: Completion;
-};
-export type CompletableFlag<T> = BooleanFlag<T> | CompletableOptionFlag<T>;
 export type FlagInput<T extends FlagOutput = {
     [flag: string]: any;
 }> = {
-    [P in keyof T]: CompletableFlag<T[P]>;
+    [P in keyof T]: Flag<T[P]>;
 };
 export type ArgInput<T extends ArgOutput = {
     [arg: string]: any;
 }> = {
     [P in keyof T]: Arg<T[P]>;
 };
+export {};

package/lib/interfaces/pjson.d.ts

@@ -1,7 +1,6 @@
 import { HelpOptions } from './help';
 export interface PJSON {
     [k: string]: any;
-    version: string;
     dependencies?: {
         [name: string]: string;
     };
@@ -9,111 +8,112 @@ export interface PJSON {
         [name: string]: string;
     };
     oclif: {
-        schema?: number;
         bin?: string;
         dirname?: string;
         hooks?: Record<string, string | string[]>;
         plugins?: string[];
+        schema?: number;
     };
+    version: string;
 }
 export declare namespace PJSON {
     interface Plugin extends PJSON {
         name: string;
-        version: string;
         oclif: PJSON['oclif'] & {
-            schema?: number;
-            description?: string;
-            topicSeparator?: ':' | ' ';
-            flexibleTaxonomy?: boolean;
-            hooks?: {
-                [name: string]: (string | string[]);
+            additionalHelpFlags?: string[];
+            additionalVersionFlags?: string[];
+            aliases?: {
+                [name: string]: null | string;
             };
             commands?: string;
             default?: string;
-            plugins?: string[];
+            description?: string;
             devPlugins?: string[];
-            jitPlugins?: Record<string, string>;
+            flexibleTaxonomy?: boolean;
             helpClass?: string;
             helpOptions?: HelpOptions;
-            aliases?: {
-                [name: string]: string | null;
+            hooks?: {
+                [name: string]: string | string[];
             };
+            jitPlugins?: Record<string, string>;
+            plugins?: string[];
             repositoryPrefix?: string;
+            schema?: number;
+            state?: 'beta' | 'deprecated' | string;
+            topicSeparator?: ' ' | ':';
+            topics?: {
+                [k: string]: {
+                    description?: string;
+                    hidden?: boolean;
+                    subtopics?: Plugin['oclif']['topics'];
+                };
+            };
             update: {
-                s3: S3;
                 autoupdate?: {
-                    rollout?: number;
                     debounce?: number;
+                    rollout?: number;
                 };
                 node: {
-                    version?: string;
                     targets?: string[];
+                    version?: string;
                 };
+                s3: S3;
             };
-            topics?: {
-                [k: string]: {
-                    description?: string;
-                    subtopics?: Plugin['oclif']['topics'];
-                    hidden?: boolean;
-                };
-            };
-            additionalHelpFlags?: string[];
-            additionalVersionFlags?: string[];
-            state?: 'beta' | 'deprecated' | string;
         };
+        version: string;
     }
     interface S3 {
         acl?: string;
         bucket?: string;
-        host?: string;
-        xz?: boolean;
         gz?: boolean;
+        host?: string;
         templates: {
             target: S3.Templates;
             vanilla: S3.Templates;
         };
+        xz?: boolean;
     }
     namespace S3 {
         interface Templates {
             baseDir?: string;
-            versioned?: string;
-            unversioned?: string;
             manifest?: string;
+            unversioned?: string;
+            versioned?: string;
         }
     }
     interface CLI extends Plugin {
         oclif: Plugin['oclif'] & {
-            schema?: number;
             bin?: string;
             binAliases?: string[];
-            nsisCustomization?: string;
-            npmRegistry?: string;
-            scope?: string;
             dirname?: string;
             flexibleTaxonomy?: boolean;
             jitPlugins?: Record<string, string>;
+            npmRegistry?: string;
+            nsisCustomization?: string;
+            schema?: number;
+            scope?: string;
         };
     }
     interface User extends PJSON {
-        private?: boolean;
         oclif: PJSON['oclif'] & {
-            plugins?: (string | PluginTypes.User | PluginTypes.Link)[];
+            plugins?: (PluginTypes.Link | PluginTypes.User | string)[];
         };
+        private?: boolean;
     }
-    type PluginTypes = PluginTypes.User | PluginTypes.Link | {
+    type PluginTypes = {
         root: string;
-    };
+    } | PluginTypes.Link | PluginTypes.User;
     namespace PluginTypes {
         interface User {
-            type: 'user';
             name: string;
-            url?: string;
             tag?: string;
+            type: 'user';
+            url?: string;
         }
         interface Link {
-            type: 'link';
             name: string;
             root: string;
+            type: 'link';
         }
     }
 }

package/lib/interfaces/plugin.d.ts

@@ -2,60 +2,67 @@ import { Command } from '../command';
 import { PJSON } from './pjson';
 import { Topic } from './topic';
 export interface PluginOptions {
-    root: string;
-    name?: string;
-    type?: string;
-    tag?: string;
-    ignoreManifest?: boolean;
-    errorOnManifestCreate?: boolean;
-    respectNoCacheDefault?: boolean;
-    parent?: Plugin;
     children?: Plugin[];
+    errorOnManifestCreate?: boolean;
     flexibleTaxonomy?: boolean;
+    ignoreManifest?: boolean;
+    isRoot?: boolean;
+    name?: string;
+    parent?: Plugin;
+    respectNoCacheDefault?: boolean;
+    root: string;
+    tag?: string;
+    type?: string;
 }
 export interface Options extends PluginOptions {
+    channel?: string;
     devPlugins?: boolean;
+    enablePerf?: boolean;
     jitPlugins?: boolean;
+    plugins?: Map<string, Plugin>;
     userPlugins?: boolean;
-    channel?: string;
     version?: string;
-    enablePerf?: boolean;
-    plugins?: Map<string, Plugin>;
 }
 export interface Plugin {
     /**
      * ../config version
      */
     _base: string;
-    /**
-     * name from package.json
-     */
-    name: string;
     /**
      * aliases from package.json dependencies
      */
     alias: string;
+    readonly commandIDs: string[];
+    commands: Command.Loadable[];
+    findCommand(id: string, opts: {
+        must: true;
+    }): Promise<Command.Class>;
+    findCommand(id: string, opts?: {
+        must: boolean;
+    }): Promise<Command.Class> | undefined;
+    readonly hasManifest: boolean;
+    hooks: {
+        [k: string]: string[];
+    };
     /**
-     * version from package.json
-     *
-     * example: 1.2.3
+     * True if the plugin is the root plugin.
      */
-    version: string;
+    isRoot: boolean;
+    load(): Promise<void>;
     /**
-     * full package.json
-     *
-     * parsed with read-pkg
+     * Plugin is written in ESM or CommonJS
      */
-    pjson: PJSON.Plugin | PJSON.CLI;
+    moduleType: 'commonjs' | 'module';
     /**
-     * used to tell the user how the plugin was installed
-     * examples: core, link, user, dev
+     * name from package.json
      */
-    type: string;
+    name: string;
     /**
-     * Plugin is written in ESM or CommonJS
+     * full package.json
+     *
+     * parsed with read-pkg
      */
-    moduleType: 'module' | 'commonjs';
+    pjson: PJSON.CLI | PJSON.Plugin;
     /**
      * base path of plugin
      */
@@ -65,21 +72,20 @@ export interface Plugin {
      * only used for user plugins
      */
     tag?: string;
+    readonly topics: Topic[];
+    /**
+     * used to tell the user how the plugin was installed
+     * examples: core, link, user, dev
+     */
+    type: string;
     /**
      * if it appears to be an npm package but does not look like it's really a CLI plugin, this is set to false
      */
     valid: boolean;
-    commands: Command.Loadable[];
-    hooks: {
-        [k: string]: string[];
-    };
-    readonly commandIDs: string[];
-    readonly topics: Topic[];
-    findCommand(id: string, opts: {
-        must: true;
-    }): Promise<Command.Class>;
-    findCommand(id: string, opts?: {
-        must: boolean;
-    }): Promise<Command.Class> | undefined;
-    load(): Promise<void>;
+    /**
+     * version from package.json
+     *
+     * example: 1.2.3
+     */
+    version: string;
 }

package/lib/interfaces/s3-manifest.d.ts

@@ -1,14 +1,14 @@
 export interface S3Manifest {
-    version: string;
-    sha: string;
-    gz: string;
-    xz?: string;
-    sha256gz: string;
-    sha256xz?: string;
     baseDir: string;
-    rollout?: number;
+    gz: string;
     node: {
         compatible: string;
         recommended: string;
     };
+    rollout?: number;
+    sha: string;
+    sha256gz: string;
+    sha256xz?: string;
+    version: string;
+    xz?: string;
 }

package/lib/interfaces/topic.d.ts

@@ -1,5 +1,5 @@
 export interface Topic {
-    name: string;
     description?: string;
     hidden?: boolean;
+    name: string;
 }

package/lib/interfaces/ts-config.d.ts

@@ -1,20 +1,20 @@
 export interface TSConfig {
     compilerOptions: {
-        rootDir?: string;
-        rootDirs?: string[];
-        outDir?: string;
-        target?: string;
+        emitDecoratorMetadata?: boolean;
         esModuleInterop?: boolean;
         experimentalDecorators?: boolean;
-        emitDecoratorMetadata?: boolean;
+        jsx?: boolean;
         module?: string;
         moduleResolution?: string;
+        outDir?: string;
+        rootDir?: string;
+        rootDirs?: string[];
         sourceMap?: boolean;
-        jsx?: boolean;
+        target?: string;
     };
     'ts-node'?: {
         esm?: boolean;
-        experimentalSpecifierResolution?: 'node' | 'explicit';
+        experimentalSpecifierResolution?: 'explicit' | 'node';
         scope?: boolean;
     };
 }

package/lib/main.d.ts

@@ -1,5 +1,5 @@
-import * as Interfaces from './interfaces';
 import { Config } from './config';
+import * as Interfaces from './interfaces';
 export declare const helpAddition: (argv: string[], config: Interfaces.Config) => boolean;
 export declare const versionAddition: (argv: string[], config?: Interfaces.Config) => boolean;
-export default function run(argv?: string[], options?: Interfaces.LoadOptions): Promise<unknown>;
+export declare function run(argv?: string[], options?: Interfaces.LoadOptions): Promise<unknown>;