@oclif/core 3.0.0-beta.2 → 3.0.0-beta.20

package/lib/errors/index.js

@@ -1,33 +1,34 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.memoizedWarn = exports.warn = exports.error = exports.exit = exports.config = exports.Logger = exports.CLIError = exports.ModuleLoadError = exports.ExitError = exports.handle = void 0;
+const tslib_1 = require("tslib");
+const cli_1 = require("./errors/cli");
+const pretty_print_1 = tslib_1.__importStar(require("./errors/pretty-print"));
+const exit_1 = require("./errors/exit");
+const config_1 = require("./config");
 var handle_1 = require("./handle");
 Object.defineProperty(exports, "handle", { enumerable: true, get: function () { return handle_1.handle; } });
-var exit_1 = require("./errors/exit");
-Object.defineProperty(exports, "ExitError", { enumerable: true, get: function () { return exit_1.ExitError; } });
+var exit_2 = require("./errors/exit");
+Object.defineProperty(exports, "ExitError", { enumerable: true, get: function () { return exit_2.ExitError; } });
 var module_load_1 = require("./errors/module-load");
 Object.defineProperty(exports, "ModuleLoadError", { enumerable: true, get: function () { return module_load_1.ModuleLoadError; } });
-var cli_1 = require("./errors/cli");
-Object.defineProperty(exports, "CLIError", { enumerable: true, get: function () { return cli_1.CLIError; } });
+var cli_2 = require("./errors/cli");
+Object.defineProperty(exports, "CLIError", { enumerable: true, get: function () { return cli_2.CLIError; } });
 var logger_1 = require("./logger");
 Object.defineProperty(exports, "Logger", { enumerable: true, get: function () { return logger_1.Logger; } });
-var config_1 = require("./config");
-Object.defineProperty(exports, "config", { enumerable: true, get: function () { return config_1.config; } });
-const config_2 = require("./config");
-const cli_2 = require("./errors/cli");
-const exit_2 = require("./errors/exit");
-const pretty_print_1 = require("./errors/pretty-print");
+var config_2 = require("./config");
+Object.defineProperty(exports, "config", { enumerable: true, get: function () { return config_2.config; } });
 function exit(code = 0) {
-    throw new exit_2.ExitError(code);
+    throw new exit_1.ExitError(code);
 }
 exports.exit = exit;
 function error(input, options = {}) {
     let err;
     if (typeof input === 'string') {
-        err = new cli_2.CLIError(input, options);
+        err = new cli_1.CLIError(input, options);
     }
     else if (input instanceof Error) {
-        err = (0, cli_2.addOclifExitCode)(input, options);
+        err = (0, cli_1.addOclifExitCode)(input, options);
     }
     else {
         throw new TypeError('first argument must be a string or instance of Error');
@@ -36,8 +37,8 @@ function error(input, options = {}) {
     if (options.exit === false) {
         const message = (0, pretty_print_1.default)(err);
         console.error(message);
-        if (config_2.config.errorLogger)
-            config_2.config.errorLogger.log(err?.stack ?? '');
+        if (config_1.config.errorLogger)
+            config_1.config.errorLogger.log(err?.stack ?? '');
     }
     else
         throw err;
@@ -46,18 +47,18 @@ exports.error = error;
 function warn(input) {
     let err;
     if (typeof input === 'string') {
-        err = new cli_2.CLIError.Warn(input);
+        err = new cli_1.CLIError.Warn(input);
     }
     else if (input instanceof Error) {
-        err = (0, cli_2.addOclifExitCode)(input);
+        err = (0, cli_1.addOclifExitCode)(input);
     }
     else {
         throw new TypeError('first argument must be a string or instance of Error');
     }
     const message = (0, pretty_print_1.default)(err);
     console.error(message);
-    if (config_2.config.errorLogger)
-        config_2.config.errorLogger.log(err?.stack ?? '');
+    if (config_1.config.errorLogger)
+        config_1.config.errorLogger.log(err?.stack ?? '');
 }
 exports.warn = warn;
 const WARNINGS = new Set();

package/lib/errors/logger.js

@@ -1,12 +1,12 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Logger = void 0;
-const fs = require("fs-extra");
-const path = require("path");
+const promises_1 = require("node:fs/promises");
+const node_path_1 = require("node:path");
 const stripAnsi = require("strip-ansi");
 const timestamp = () => new Date().toISOString();
 let timer;
-const wait = (ms) => new Promise(resolve => {
+const wait = (ms) => new Promise((resolve) => {
     if (timer)
         timer.unref();
     timer = setTimeout(() => resolve(null), ms);
@@ -17,14 +17,15 @@ function chomp(s) {
     return s;
 }
 class Logger {
+    file;
+    flushing = Promise.resolve();
+    buffer = [];
     constructor(file) {
         this.file = file;
-        this.flushing = Promise.resolve();
-        this.buffer = [];
     }
     log(msg) {
         msg = stripAnsi(chomp(msg));
-        const lines = msg.split('\n').map(l => `${timestamp()} ${l}`.trimEnd());
+        const lines = msg.split('\n').map((l) => `${timestamp()} ${l}`.trimEnd());
         this.buffer.push(...lines);
         this.flush(50).catch(console.error);
     }
@@ -35,8 +36,8 @@ class Logger {
                 return;
             const mylines = this.buffer;
             this.buffer = [];
-            await fs.mkdirp(path.dirname(this.file));
-            await fs.appendFile(this.file, mylines.join('\n') + '\n');
+            await (0, promises_1.mkdir)((0, node_path_1.dirname)(this.file), { recursive: true });
+            await (0, promises_1.appendFile)(this.file, mylines.join('\n') + '\n');
         });
         await this.flushing;
     }

package/lib/execute.d.ts

@@ -0,0 +1,49 @@
+import { LoadOptions } from './interfaces';
+/**
+ * Load and run oclif CLI
+ *
+ * @param options - options to load the CLI
+ * @returns Promise<void>
+ *
+ * @example For ESM dev.js
+ * ```
+ * #!/usr/bin/env ts-node
+ * void (async () => {
+ *   const oclif = await import('@oclif/core')
+ *   await oclif.execute({development: true, dir: import.meta.url})
+ * })()
+ * ```
+ *
+ * @example For ESM run.js
+ * ```
+ * #!/usr/bin/env node
+ * void (async () => {
+ *   const oclif = await import('@oclif/core')
+ *   await oclif.execute({dir: import.meta.url})
+ * })()
+ * ```
+ *
+ * @example For CJS dev.js
+ * ```
+ * #!/usr/bin/env ts-node
+ * void (async () => {
+ *   const oclif = await import('@oclif/core')
+ *   await oclif.execute({development: true, dir: __dirname})
+ * })()
+ * ```
+ *
+ * @example For CJS run.js
+ * ```
+ * #!/usr/bin/env node
+ * void (async () => {
+ *   const oclif = await import('@oclif/core')
+ *   await oclif.execute({dir: __dirname})
+ * })()
+ * ```
+ */
+export declare function execute(options: {
+    dir: string;
+    args?: string[];
+    loadOptions?: LoadOptions;
+    development?: boolean;
+}): Promise<unknown>;

package/lib/execute.js

@@ -0,0 +1,63 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.execute = void 0;
+const flush_1 = require("./cli-ux/flush");
+const handle_1 = require("./errors/handle");
+const main_1 = require("./main");
+const settings_1 = require("./settings");
+/**
+ * Load and run oclif CLI
+ *
+ * @param options - options to load the CLI
+ * @returns Promise<void>
+ *
+ * @example For ESM dev.js
+ * ```
+ * #!/usr/bin/env ts-node
+ * void (async () => {
+ *   const oclif = await import('@oclif/core')
+ *   await oclif.execute({development: true, dir: import.meta.url})
+ * })()
+ * ```
+ *
+ * @example For ESM run.js
+ * ```
+ * #!/usr/bin/env node
+ * void (async () => {
+ *   const oclif = await import('@oclif/core')
+ *   await oclif.execute({dir: import.meta.url})
+ * })()
+ * ```
+ *
+ * @example For CJS dev.js
+ * ```
+ * #!/usr/bin/env ts-node
+ * void (async () => {
+ *   const oclif = await import('@oclif/core')
+ *   await oclif.execute({development: true, dir: __dirname})
+ * })()
+ * ```
+ *
+ * @example For CJS run.js
+ * ```
+ * #!/usr/bin/env node
+ * void (async () => {
+ *   const oclif = await import('@oclif/core')
+ *   await oclif.execute({dir: __dirname})
+ * })()
+ * ```
+ */
+async function execute(options) {
+    if (options.development) {
+        // In dev mode -> use ts-node and dev plugins
+        process.env.NODE_ENV = 'development';
+        settings_1.settings.debug = true;
+    }
+    return (0, main_1.run)(options.args ?? process.argv.slice(2), options.loadOptions ?? options.dir)
+        .then(async (result) => {
+        (0, flush_1.flush)();
+        return result;
+    })
+        .catch(async (error) => (0, handle_1.handle)(error));
+}
+exports.execute = execute;

package/lib/flags.d.ts

@@ -1,49 +1,120 @@
 /// <reference types="node" />
-import { URL } from 'url';
-import { BooleanFlag } from './interfaces';
-import { FlagDefinition, OptionFlagDefaults, FlagParser } 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<OptionFlagDefaults<T, P, true>>): FlagDefinition<T, P>;
-export declare function custom<T, P = Record<string, unknown>>(defaults: {
-    parse: FlagParser<T, string, P>;
-} & Partial<OptionFlagDefaults<T, P>>): FlagDefinition<T, P>;
-export declare function custom<T = string, P = Record<string, unknown>>(defaults: Partial<OptionFlagDefaults<T, P>>): FlagDefinition<T, P>;
+import { BooleanFlag, CustomOptions, FlagDefinition, OptionFlag } from './interfaces';
+import { URL } from 'node:url';
+type NotArray<T> = T extends Array<any> ? never : T;
+export declare function custom<T = string, P extends CustomOptions = CustomOptions>(defaults: Partial<OptionFlag<T[], P>> & {
+    multiple: true;
+} & ({
+    required: true;
+} | {
+    default: OptionFlag<T[], P>['default'];
+})): FlagDefinition<T, P, {
+    multiple: true;
+    requiredOrDefaulted: true;
+}>;
+export declare function custom<T = string, P extends CustomOptions = CustomOptions>(defaults: Partial<OptionFlag<NotArray<T>, P>> & {
+    multiple?: false | undefined;
+} & ({
+    required: true;
+} | {
+    default: OptionFlag<NotArray<T>, P>['default'];
+})): FlagDefinition<T, P, {
+    multiple: false;
+    requiredOrDefaulted: true;
+}>;
+export declare function custom<T = string, P extends CustomOptions = CustomOptions>(defaults: Partial<OptionFlag<NotArray<T>, P>> & {
+    default?: OptionFlag<NotArray<T>, P>['default'] | undefined;
+    multiple?: false | undefined;
+    required?: false | undefined;
+}): FlagDefinition<T, P, {
+    multiple: false;
+    requiredOrDefaulted: false;
+}>;
+export declare function custom<T = string, P extends CustomOptions = CustomOptions>(defaults: Partial<OptionFlag<T[], P>> & {
+    multiple: true;
+    default?: OptionFlag<T[], P>['default'] | undefined;
+    required?: false | undefined;
+}): FlagDefinition<T, P, {
+    multiple: true;
+    requiredOrDefaulted: false;
+}>;
+export declare function custom<T = string, P extends CustomOptions = CustomOptions>(): FlagDefinition<T, P, {
+    multiple: false;
+    requiredOrDefaulted: false;
+}>;
 export declare function boolean<T = boolean>(options?: Partial<BooleanFlag<T>>): BooleanFlag<T>;
 export declare const integer: FlagDefinition<number, {
     min?: number | undefined;
     max?: number | undefined;
+}, {
+    multiple: false;
+    requiredOrDefaulted: false;
 }>;
 export declare const directory: FlagDefinition<string, {
     exists?: boolean | undefined;
+}, {
+    multiple: false;
+    requiredOrDefaulted: false;
 }>;
 export declare const file: FlagDefinition<string, {
     exists?: boolean | undefined;
+}, {
+    multiple: false;
+    requiredOrDefaulted: false;
 }>;
 /**
  * Initializes a string as a URL. Throws an error
  * if the string is not a valid URL.
  */
-export declare const url: FlagDefinition<URL, Record<string, unknown>>;
-declare const stringFlag: FlagDefinition<string, Record<string, unknown>>;
-export { stringFlag as string };
+export declare const url: FlagDefinition<URL, CustomOptions, {
+    multiple: false;
+    requiredOrDefaulted: false;
+}>;
+export declare const string: FlagDefinition<string, CustomOptions, {
+    multiple: false;
+    requiredOrDefaulted: false;
+}>;
 export declare const version: (opts?: Partial<BooleanFlag<boolean>>) => BooleanFlag<void>;
 export declare const help: (opts?: Partial<BooleanFlag<boolean>>) => BooleanFlag<void>;
+type ElementType<T extends ReadonlyArray<unknown>> = T[number];
+export declare function option<T extends readonly string[], P extends CustomOptions>(defaults: Partial<OptionFlag<ElementType<T>[], P>> & {
+    options: T;
+    multiple: true;
+} & ({
+    required: true;
+} | {
+    default: OptionFlag<ElementType<T>[], P>['default'] | undefined;
+})): FlagDefinition<(typeof defaults.options)[number], P, {
+    multiple: true;
+    requiredOrDefaulted: true;
+}>;
+export declare function option<T extends readonly string[], P extends CustomOptions>(defaults: Partial<OptionFlag<ElementType<T>, P>> & {
+    options: T;
+    multiple?: false | undefined;
+} & ({
+    required: true;
+} | {
+    default: OptionFlag<ElementType<T>, P>['default'];
+})): FlagDefinition<(typeof defaults.options)[number], P, {
+    multiple: false;
+    requiredOrDefaulted: true;
+}>;
+export declare function option<T extends readonly string[], P extends CustomOptions>(defaults: Partial<OptionFlag<ElementType<T>, P>> & {
+    options: T;
+    default?: OptionFlag<ElementType<T>, P>['default'] | undefined;
+    multiple?: false | undefined;
+    required?: false | undefined;
+}): FlagDefinition<(typeof defaults.options)[number], P, {
+    multiple: false;
+    requiredOrDefaulted: false;
+}>;
+export declare function option<T extends readonly string[], P extends CustomOptions>(defaults: Partial<OptionFlag<ElementType<T>[], P>> & {
+    options: T;
+    multiple: true;
+    default?: OptionFlag<ElementType<T>[], P>['default'] | undefined;
+    required?: false | undefined;
+}): FlagDefinition<(typeof defaults.options)[number], P, {
+    multiple: true;
+    requiredOrDefaulted: false;
+}>;
+export {};

package/lib/flags.js

@@ -1,20 +1,36 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.help = exports.version = exports.string = exports.url = exports.file = exports.directory = exports.integer = exports.boolean = exports.custom = void 0;
-const url_1 = require("url");
+exports.option = exports.help = exports.version = exports.string = exports.url = exports.file = exports.directory = exports.integer = exports.boolean = exports.custom = void 0;
+const fs_1 = require("./util/fs");
+const errors_1 = require("./errors");
+const node_url_1 = require("node:url");
 const help_1 = require("./help");
-const util_1 = require("./util");
+/**
+ * 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')
+ *   },
+ * })
+ */
 function custom(defaults) {
-    return (options = {}) => {
-        return {
-            parse: async (input, _ctx, _opts) => input,
-            ...defaults,
-            ...options,
-            input: [],
-            multiple: Boolean(options.multiple === undefined ? defaults.multiple : options.multiple),
-            type: 'option',
-        };
-    };
+    return (options = {}) => ({
+        parse: async (input, _ctx, _opts) => input,
+        ...defaults,
+        ...options,
+        input: [],
+        multiple: Boolean(options.multiple === undefined ? defaults?.multiple ?? false : options.multiple),
+        type: 'option',
+    });
 }
 exports.custom = custom;
 function boolean(options = {}) {
@@ -27,28 +43,28 @@ function boolean(options = {}) {
 }
 exports.boolean = boolean;
 exports.integer = custom({
-    parse: async (input, _, opts) => {
+    async parse(input, _, opts) {
         if (!/^-?\d+$/.test(input))
-            throw new Error(`Expected an integer but received: ${input}`);
+            throw new errors_1.CLIError(`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}`);
+            throw new errors_1.CLIError(`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}`);
+            throw new errors_1.CLIError(`Expected an integer less than or equal to ${opts.max} but received: ${input}`);
         return num;
     },
 });
 exports.directory = custom({
-    parse: async (input, _, opts) => {
+    async parse(input, _, opts) {
         if (opts.exists)
-            return (0, util_1.dirExists)(input);
+            return (0, fs_1.dirExists)(input);
         return input;
     },
 });
 exports.file = custom({
-    parse: async (input, _, opts) => {
+    async parse(input, _, opts) {
         if (opts.exists)
-            return (0, util_1.fileExists)(input);
+            return (0, fs_1.fileExists)(input);
         return input;
     },
 });
@@ -57,36 +73,55 @@ exports.file = custom({
  * if the string is not a valid URL.
  */
 exports.url = custom({
-    parse: async (input) => {
+    async parse(input) {
         try {
-            return new url_1.URL(input);
+            return new node_url_1.URL(input);
         }
         catch {
-            throw new Error(`Expected a valid url but received: ${input}`);
+            throw new errors_1.CLIError(`Expected a valid url but received: ${input}`);
         }
     },
 });
-const stringFlag = custom({});
-exports.string = stringFlag;
-const version = (opts = {}) => {
-    return boolean({
-        description: 'Show CLI version.',
-        ...opts,
-        parse: async (_, ctx) => {
-            ctx.log(ctx.config.userAgent);
-            ctx.exit(0);
-        },
-    });
-};
+exports.string = custom();
+const version = (opts = {}) => boolean({
+    description: 'Show CLI version.',
+    ...opts,
+    async parse(_, ctx) {
+        ctx.log(ctx.config.userAgent);
+        ctx.exit(0);
+    },
+});
 exports.version = version;
-const help = (opts = {}) => {
-    return boolean({
-        description: 'Show CLI help.',
-        ...opts,
-        parse: async (_, cmd) => {
-            new help_1.Help(cmd.config).showHelp(cmd.id ? [cmd.id, ...cmd.argv] : cmd.argv);
-            cmd.exit(0);
-        },
-    });
-};
+const help = (opts = {}) => boolean({
+    description: 'Show CLI help.',
+    ...opts,
+    async parse(_, cmd) {
+        const Help = await (0, help_1.loadHelpClass)(cmd.config);
+        await new Help(cmd.config, cmd.config.pjson.helpOptions).showHelp(cmd.id ? [cmd.id, ...cmd.argv] : cmd.argv);
+        cmd.exit(0);
+    },
+});
 exports.help = help;
+/**
+ * Create a custom flag that infers the flag type from the provided options.
+ *
+ * @example
+ * export default class MyCommand extends Command {
+ *   static flags = {
+ *     name: Flags.option({
+ *       options: ['foo', 'bar'] as const,
+ *     })(),
+ *   }
+ * }
+ */
+function option(defaults) {
+    return (options = {}) => ({
+        parse: async (input, _ctx, _opts) => input,
+        ...defaults,
+        ...options,
+        input: [],
+        multiple: Boolean(options.multiple === undefined ? defaults.multiple : options.multiple),
+        type: 'option',
+    });
+}
+exports.option = option;

package/lib/help/command.d.ts

@@ -27,5 +27,7 @@ export declare class CommandHelp extends HelpFormatter {
     protected flagHelpLabel(flag: Command.Flag.Any, showOptions?: boolean): string;
     protected flags(flags: Array<Command.Flag.Any>): [string, string | undefined][] | undefined;
     protected flagsDescriptions(flags: Array<Command.Flag.Any>): string | undefined;
+    private formatIfCommand;
+    private isCommand;
 }
 export default CommandHelp;