@oclif/core 3.19.0 → 3.19.2-qa.0

package/lib/config/config.d.ts

@@ -18,6 +18,7 @@ export declare class Config implements IConfig {
     errlog: string;
     flexibleTaxonomy: boolean;
     home: string;
+    isSingleCommandCLI: boolean;
     name: string;
     npmRegistry?: string;
     nsisCustomization?: string;

package/lib/config/config.js

@@ -98,6 +98,7 @@ class Config {
     errlog;
     flexibleTaxonomy;
     home;
+    isSingleCommandCLI = false;
     name;
     npmRegistry;
     nsisCustomization;
@@ -328,6 +329,10 @@ class Config {
                 ...(s3.templates && s3.templates.vanilla),
             },
         };
+        this.isSingleCommandCLI = Boolean(this.pjson.oclif.default ||
+            (typeof this.pjson.oclif.commands !== 'string' &&
+                this.pjson.oclif.commands?.strategy === 'single' &&
+                this.pjson.oclif.commands?.target));
         await this.loadPluginsAndCommands();
         debug('config done');
         marker?.addDetails({

package/lib/config/plugin.d.ts

@@ -29,6 +29,8 @@ export declare class Plugin implements IPlugin {
     protected warned: boolean;
     _base: string;
     protected _debug: (..._: any) => void;
+    private commandCache;
+    private commandDiscoveryOpts;
     private flexibleTaxonomy;
     constructor(options: PluginOptions);
     get topics(): Topic[];
@@ -42,6 +44,9 @@ export declare class Plugin implements IPlugin {
     private _manifest;
     private addErrorScope;
     private getCommandIDs;
+    private getCommandIdsFromPattern;
+    private getCommandIdsFromTarget;
     private getCommandsDir;
+    private loadCommandsFromTarget;
     private warn;
 }

package/lib/config/plugin.js

@@ -10,6 +10,7 @@ const node_util_1 = require("node:util");
 const errors_1 = require("../errors");
 const module_loader_1 = require("../module-loader");
 const performance_1 = require("../performance");
+const symbols_1 = require("../symbols");
 const cache_command_1 = require("../util/cache-command");
 const find_root_1 = require("../util/find-root");
 const fs_1 = require("../util/fs");
@@ -30,7 +31,7 @@ function topicsToArray(input, base) {
     });
 }
 const cachedCommandCanBeUsed = (manifest, id) => Boolean(manifest?.commands[id] && 'isESM' in manifest.commands[id] && 'relativePath' in manifest.commands[id]);
-const search = (cmd) => {
+const searchForCommandClass = (cmd) => {
     if (typeof cmd.run === 'function')
         return cmd;
     if (cmd.default && cmd.default.run)
@@ -47,9 +48,24 @@ function processCommandIds(files) {
         const topics = p.dir.split('/');
         const command = p.name !== 'index' && p.name;
         const id = [...topics, command].filter(Boolean).join(':');
-        return id === '' ? '.' : id;
+        return id === '' ? symbols_1.SINGLE_COMMAND_CLI_SYMBOL : id;
     });
 }
+function determineCommandDiscoveryOptions(commandDiscovery, defaultCmdId) {
+    if (!commandDiscovery)
+        return;
+    if (typeof commandDiscovery === 'string' && defaultCmdId) {
+        return { strategy: 'single', target: commandDiscovery };
+    }
+    if (typeof commandDiscovery === 'string') {
+        return { globPatterns: GLOB_PATTERNS, strategy: 'pattern', target: commandDiscovery };
+    }
+    if (!commandDiscovery.target)
+        throw new errors_1.CLIError('`oclif.commandDiscovery.target` is required.');
+    if (!commandDiscovery.strategy)
+        throw new errors_1.CLIError('`oclif.commandDiscovery.strategy` is required.');
+    return commandDiscovery;
+}
 class Plugin {
     options;
     alias;
@@ -76,6 +92,8 @@ class Plugin {
     _base = `${_pjson.name}@${_pjson.version}`;
     // eslint-disable-next-line new-cap
     _debug = (0, util_2.Debug)();
+    commandCache;
+    commandDiscoveryOpts;
     flexibleTaxonomy;
     constructor(options) {
         this.options = options;
@@ -89,32 +107,43 @@ class Plugin {
             plugin: this.name,
         });
         const fetch = async () => {
-            const commandsDir = await this.getCommandsDir();
-            if (!commandsDir)
-                return;
-            let module;
-            let isESM;
-            let filePath;
-            try {
-                ;
-                ({ filePath, isESM, module } = cachedCommandCanBeUsed(this.manifest, id)
-                    ? await (0, module_loader_1.loadWithDataFromManifest)(this.manifest.commands[id], this.root)
-                    : await (0, module_loader_1.loadWithData)(this, (0, node_path_1.join)(commandsDir ?? this.pjson.oclif.commands, ...id.split(':'))));
-                this._debug(isESM ? '(import)' : '(require)', filePath);
+            if (this.commandDiscoveryOpts?.strategy === 'pattern') {
+                const commandsDir = await this.getCommandsDir();
+                if (!commandsDir)
+                    return;
+                let module;
+                let isESM;
+                let filePath;
+                try {
+                    ;
+                    ({ filePath, isESM, module } = cachedCommandCanBeUsed(this.manifest, id)
+                        ? await (0, module_loader_1.loadWithDataFromManifest)(this.manifest.commands[id], this.root)
+                        : await (0, module_loader_1.loadWithData)(this, (0, node_path_1.join)(commandsDir ?? this.pjson.oclif.commands, ...id.split(':'))));
+                    this._debug(isESM ? '(import)' : '(require)', filePath);
+                }
+                catch (error) {
+                    if (!opts.must && error.code === 'MODULE_NOT_FOUND')
+                        return;
+                    throw error;
+                }
+                const cmd = searchForCommandClass(module);
+                if (!cmd)
+                    return;
+                cmd.id = id;
+                cmd.plugin = this;
+                cmd.isESM = isESM;
+                cmd.relativePath = (0, node_path_1.relative)(this.root, filePath || '').split(node_path_1.sep);
+                return cmd;
             }
-            catch (error) {
-                if (!opts.must && error.code === 'MODULE_NOT_FOUND')
+            if (this.commandDiscoveryOpts?.strategy === 'single' || this.commandDiscoveryOpts?.strategy === 'explicit') {
+                const commandCache = await this.loadCommandsFromTarget();
+                const cmd = commandCache?.[id];
+                if (!cmd)
                     return;
-                throw error;
+                cmd.id = id;
+                cmd.plugin = this;
+                return cmd;
             }
-            const cmd = search(module);
-            if (!cmd)
-                return;
-            cmd.id = id;
-            cmd.plugin = this;
-            cmd.isESM = isESM;
-            cmd.relativePath = (0, node_path_1.relative)(this.root, filePath || '').split(node_path_1.sep);
-            return cmd;
         };
         const cmd = await fetch();
         if (!cmd && opts.must)
@@ -154,6 +183,8 @@ class Plugin {
             this.pjson.oclif = this.pjson['cli-engine'] || {};
         }
         this.hooks = Object.fromEntries(Object.entries(this.pjson.oclif.hooks ?? {}).map(([k, v]) => [k, (0, util_1.castArray)(v)]));
+        this.commandDiscoveryOpts = determineCommandDiscoveryOptions(this.pjson.oclif?.commands, this.pjson.oclif?.default);
+        this._debug('command discovery options', this.commandDiscoveryOpts);
         this.manifest = await this._manifest();
         this.commands = Object.entries(this.manifest.commands)
             .map(([id, c]) => ({
@@ -205,7 +236,13 @@ class Plugin {
         const manifest = {
             commands: (await Promise.all(this.commandIDs.map(async (id) => {
                 try {
-                    const cached = await (0, cache_command_1.cacheCommand)(await this.findCommand(id, { must: true }), this, respectNoCacheDefault);
+                    const found = await this.findCommand(id, { must: true });
+                    const cached = await (0, cache_command_1.cacheCommand)(found, this, respectNoCacheDefault);
+                    // Ensure that id is set to the id being processed
+                    // This is necessary because the id is set by findCommand but if there
+                    // are multiple instances of a Command, then the id will be set to the
+                    // last one found.
+                    cached.id = id;
                     if (this.flexibleTaxonomy) {
                         const permutations = (0, util_2.getCommandIdPermutations)(id);
                         const aliasPermutations = cached.aliases.flatMap((a) => (0, util_2.getCommandIdPermutations)(a));
@@ -246,24 +283,66 @@ class Plugin {
         return err;
     }
     async getCommandIDs() {
-        const commandsDir = await this.getCommandsDir();
-        if (!commandsDir)
-            return [];
         const marker = performance_1.Performance.mark(performance_1.OCLIF_MARKER_OWNER, `plugin.getCommandIDs#${this.name}`, { plugin: this.name });
-        this._debug(`loading IDs from ${commandsDir}`);
-        const files = await (0, globby_1.default)(GLOB_PATTERNS, { cwd: commandsDir });
-        const ids = processCommandIds(files);
+        let ids;
+        switch (this.commandDiscoveryOpts?.strategy) {
+            case 'explicit': {
+                ids = (await this.getCommandIdsFromTarget()) ?? [];
+                break;
+            }
+            case 'pattern': {
+                ids = await this.getCommandIdsFromPattern();
+                break;
+            }
+            case 'single': {
+                ids = (await this.getCommandIdsFromTarget()) ?? [];
+                break;
+            }
+            default: {
+                ids = [];
+            }
+        }
         this._debug('found commands', ids);
         marker?.addDetails({ count: ids.length });
         marker?.stop();
         return ids;
     }
+    async getCommandIdsFromPattern() {
+        const commandsDir = await this.getCommandsDir();
+        if (!commandsDir)
+            return [];
+        this._debug(`loading IDs from ${commandsDir}`);
+        const files = await (0, globby_1.default)(this.commandDiscoveryOpts?.globPatterns ?? GLOB_PATTERNS, { cwd: commandsDir });
+        return processCommandIds(files);
+    }
+    async getCommandIdsFromTarget() {
+        const commandsFromExport = await this.loadCommandsFromTarget();
+        if (commandsFromExport) {
+            return Object.keys(commandsFromExport);
+        }
+    }
     async getCommandsDir() {
         if (this.commandsDir)
             return this.commandsDir;
-        this.commandsDir = await (0, ts_node_1.tsPath)(this.root, this.pjson.oclif.commands, this);
+        this.commandsDir = await (0, ts_node_1.tsPath)(this.root, this.commandDiscoveryOpts?.target, this);
         return this.commandsDir;
     }
+    async loadCommandsFromTarget() {
+        if (this.commandCache)
+            return this.commandCache;
+        if (this.commandDiscoveryOpts?.strategy === 'explicit' && this.commandDiscoveryOpts.target) {
+            const filePath = await (0, ts_node_1.tsPath)(this.root, this.commandDiscoveryOpts.target, this);
+            const module = await (0, module_loader_1.load)(this, filePath);
+            this.commandCache = module.default ?? {};
+            return this.commandCache;
+        }
+        if (this.commandDiscoveryOpts?.strategy === 'single' && this.commandDiscoveryOpts.target) {
+            const filePath = await (0, ts_node_1.tsPath)(this.root, this.commandDiscoveryOpts?.target ?? this.root, this);
+            const module = await (0, module_loader_1.load)(this, filePath);
+            this.commandCache = { [symbols_1.SINGLE_COMMAND_CLI_SYMBOL]: searchForCommandClass(module) };
+            return this.commandCache;
+        }
+    }
     warn(err, scope) {
         if (this.warned)
             return;

package/lib/help/docopts.js

@@ -77,7 +77,7 @@ class DocOpts {
         return new DocOpts(cmd).toString();
     }
     toString() {
-        const opts = this.cmd.id === '.' || this.cmd.id === '' ? [] : ['<%= command.id %>'];
+        const opts = ['<%= command.id %>'];
         if (this.cmd.args) {
             const a = Object.values((0, ensure_arg_object_1.ensureArgObject)(this.cmd.args)).map((arg) => arg.required ? arg.name.toUpperCase() : `[${arg.name.toUpperCase()}]`) || [];
             opts.push(...a);

package/lib/help/index.js

@@ -10,6 +10,7 @@ const theme_1 = require("../cli-ux/theme");
 const write_1 = __importDefault(require("../cli-ux/write"));
 const errors_1 = require("../errors");
 const module_loader_1 = require("../module-loader");
+const symbols_1 = require("../symbols");
 const cache_default_value_1 = require("../util/cache-default-value");
 const ids_1 = require("../util/ids");
 const util_1 = require("../util/util");
@@ -189,8 +190,8 @@ class Help extends HelpBase {
             argv = (0, util_2.standardizeIDFromArgv)(argv, this.config);
         const subject = getHelpSubject(argv, this.config);
         if (!subject) {
-            if (this.config.pjson.oclif.default) {
-                const rootCmd = this.config.findCommand(this.config.pjson.oclif.default);
+            if (this.config.isSingleCommandCLI) {
+                const rootCmd = this.config.findCommand(symbols_1.SINGLE_COMMAND_CLI_SYMBOL);
                 if (rootCmd) {
                     await this.showCommandHelp(rootCmd);
                     return;
@@ -201,6 +202,12 @@ class Help extends HelpBase {
         }
         const command = this.config.findCommand(subject);
         if (command) {
+            if (command.id === symbols_1.SINGLE_COMMAND_CLI_SYMBOL) {
+                // If the command is the root command of a single command CLI,
+                // then set the command id to an empty string to prevent the
+                // the SINGLE_COMMAND_CLI_SYMBOL from being displayed in the help output.
+                command.id = '';
+            }
             if (command.hasDynamicHelp && command.pluginType !== 'jit') {
                 const loaded = await command.load();
                 for (const [name, flag] of Object.entries(loaded.flags ?? {})) {

package/lib/interfaces/config.d.ts

@@ -96,6 +96,7 @@ export interface Config {
      * example: /home/myuser
      */
     readonly home: string;
+    readonly isSingleCommandCLI: boolean;
     readonly name: string;
     /**
      * npm registry to use for installing plugins

package/lib/interfaces/pjson.d.ts

@@ -16,6 +16,45 @@ export interface PJSON {
     };
     version: string;
 }
+export type CommandDiscovery = {
+    /**
+     * The strategy to use for loading commands.
+     *
+     * - `pattern` will use glob patterns to find command files in the specified `directory`.
+     * - `explicit` will use `import` (or `require` for CJS) to load the commands from the
+     *    specified `file`.
+     * - `single` will use the `target` which should export a command class. This is for CLIs that
+     *    only have a single command.
+     *
+     * In both cases, the `oclif.manifest.json` file will be used to find the commands if it exists.
+     */
+    strategy: 'pattern' | 'explicit' | 'single';
+    /**
+     * If the `strategy` is `pattern`, this is the **directory** to use to find command files.
+     *
+     * If the `strategy` is `explicit`, this is the **file** that default exports the commands.
+     *   - This export must be the default export and an object with keys that are the command names
+     *     and values that are the command classes.
+     *
+     * @example
+     * ```typescript
+     * // in src/commands.ts
+     * import Hello from './commands/hello/index.js'
+     * import HelloWorld from './commands/hello/world.js'
+     *
+     * export default {
+     *   hello: Hello,
+     *   'hello:world': HelloWorld,
+     * }
+     * ```
+     */
+    target: string;
+    /**
+     * The glob patterns to use to find command files when no `oclif.manifest.json` is present.
+     * This is only used when `strategy` is `pattern`.
+     */
+    globPatterns?: string[];
+};
 export declare namespace PJSON {
     interface Plugin extends PJSON {
         name: string;
@@ -25,7 +64,13 @@ export declare namespace PJSON {
             aliases?: {
                 [name: string]: null | string;
             };
-            commands?: string;
+            commands?: string | CommandDiscovery;
+            /**
+             * Default command id when no command is found. This is used to support single command CLIs.
+             * Only supported value is "."
+             *
+             * @deprecated Use `commands.strategy: 'single'` instead.
+             */
             default?: string;
             description?: string;
             devPlugins?: string[];

package/lib/main.js

@@ -6,9 +6,10 @@ const cli_ux_1 = require("./cli-ux");
 const config_1 = require("./config");
 const help_1 = require("./help");
 const performance_1 = require("./performance");
+const symbols_1 = require("./symbols");
 const debug = require('debug')('oclif:main');
 const helpAddition = (argv, config) => {
-    if (argv.length === 0 && !config.pjson.oclif.default)
+    if (argv.length === 0 && !config.isSingleCommandCLI)
         return true;
     const mergedHelpFlags = (0, help_1.getHelpFlagAdditions)(config);
     for (const arg of argv) {
@@ -47,7 +48,11 @@ async function run(argv, options) {
         options = (0, node_url_1.fileURLToPath)(options);
     }
     const config = await config_1.Config.load(options ?? require.main?.filename ?? __dirname);
-    let [id, ...argvSlice] = (0, help_1.normalizeArgv)(config, argv);
+    // If this is a single command CLI, then insert the SINGLE_COMMAND_CLI_SYMBOL into the argv array to serve as the command id.
+    if (config.isSingleCommandCLI) {
+        argv = [symbols_1.SINGLE_COMMAND_CLI_SYMBOL, ...argv];
+    }
+    const [id, ...argvSlice] = (0, help_1.normalizeArgv)(config, argv);
     // run init hook
     await config.runHook('init', { argv: argvSlice, id });
     // display version if applicable
@@ -70,17 +75,8 @@ async function run(argv, options) {
         const topic = config.flexibleTaxonomy ? null : config.findTopic(id);
         if (topic)
             return config.runCommand('help', [id]);
-        if (config.pjson.oclif.default) {
-            id = config.pjson.oclif.default;
-            argvSlice = argv;
-        }
     }
     initMarker?.stop();
-    // If the the default command is '.' (signifying that the CLI is a single command CLI) and '.' is provided
-    // as an argument, we need to add back the '.' to argv since it was stripped out earlier as part of the
-    // command id.
-    if (config.pjson.oclif.default === '.' && id === '.' && argv[0] === '.')
-        argvSlice = ['.', ...argvSlice];
     try {
         return await config.runCommand(id, argvSlice, cmd);
     }

package/lib/parser/parse.d.ts

@@ -1,4 +1,18 @@
 import { OutputArgs, OutputFlags, ParserInput, ParserOutput } from '../interfaces/parser';
+declare global {
+    /**
+     * Cache the stdin so that it can be read multiple times.
+     *
+     * This fixes a bug where the stdin would be read multiple times (because Parser.parse() was called more than once)
+     * but only the first read would be successful - all other reads would return null.
+     *
+     * Storing in global is necessary because we want the cache to be shared across all versions of @oclif/core in
+     * in the dependency tree. Storing in a variable would only share the cache within the same version of @oclif/core.
+     */
+    var oclif: {
+        stdinCache?: string;
+    };
+}
 export declare const readStdin: () => Promise<null | string>;
 export declare class Parser<T extends ParserInput, TFlags extends OutputFlags<T['flags']>, BFlags extends OutputFlags<T['flags']>, TArgs extends OutputArgs<T['args']>> {
     private readonly input;

package/lib/parser/parse.js

@@ -32,11 +32,15 @@ const readStdin = async () => {
     // Because of this, we have to set a timeout to prevent the process from hanging.
     if (stdin.isTTY)
         return null;
+    if (global.oclif?.stdinCache) {
+        debug('resolved stdin from global cache', global.oclif.stdinCache);
+        return global.oclif.stdinCache;
+    }
     return new Promise((resolve) => {
         let result = '';
         const ac = new AbortController();
         const { signal } = ac;
-        const timeout = setTimeout(() => ac.abort(), 100);
+        const timeout = setTimeout(() => ac.abort(), 10);
         const rl = (0, node_readline_1.createInterface)({
             input: stdin,
             output: stdout,
@@ -48,6 +52,7 @@ const readStdin = async () => {
         rl.once('close', () => {
             clearTimeout(timeout);
             debug('resolved from stdin', result);
+            global.oclif = { ...global.oclif, stdinCache: result };
             resolve(result);
         });
         signal.addEventListener('abort', () => {
@@ -85,6 +90,7 @@ class Parser {
     }
     async parse() {
         this._debugInput();
+        // eslint-disable-next-line complexity
         const parseFlag = async (arg) => {
             const { isLong, name } = this.findFlag(arg);
             if (!name) {
@@ -107,19 +113,19 @@ class Parser {
                 }
                 this.currentFlag = flag;
                 let input = isLong || arg.length < 3 ? this.argv.shift() : arg.slice(arg[2] === '=' ? 3 : 2);
-                // if the value ends up being one of the command's flags, the user didn't provide an input
-                if (typeof input !== 'string' || this.findFlag(input).name) {
-                    throw new errors_1.CLIError(`Flag --${name} expects a value`);
-                }
-                if (flag.allowStdin === 'only' && input !== '-') {
-                    throw new errors_1.CLIError(`Flag --${name} can only be read from stdin. The value must be "-".`);
+                if (flag.allowStdin === 'only' && input !== '-' && input !== undefined) {
+                    throw new errors_1.CLIError(`Flag --${name} can only be read from stdin. The value must be "-" or not provided at all.`);
                 }
-                if (flag.allowStdin && input === '-') {
+                if ((flag.allowStdin && input === '-') || flag.allowStdin === 'only') {
                     const stdin = await (0, exports.readStdin)();
                     if (stdin) {
                         input = stdin.trim();
                     }
                 }
+                // if the value ends up being one of the command's flags, the user didn't provide an input
+                if (typeof input !== 'string' || this.findFlag(input).name) {
+                    throw new errors_1.CLIError(`Flag --${name} expects a value`);
+                }
                 this.raw.push({ flag: flag.name, input, type: 'flag' });
             }
             else {

package/lib/symbols.d.ts

@@ -0,0 +1 @@
+export declare const SINGLE_COMMAND_CLI_SYMBOL: string;

package/lib/symbols.js

@@ -0,0 +1,4 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SINGLE_COMMAND_CLI_SYMBOL = void 0;
+exports.SINGLE_COMMAND_CLI_SYMBOL = Symbol('SINGLE_COMMAND_CLI').toString();

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@oclif/core",
   "description": "base library for oclif CLIs",
-  "version": "3.19.0",
+  "version": "3.19.2-qa.0",
   "author": "Salesforce",
   "bugs": "https://github.com/oclif/core/issues",
   "dependencies": {
@@ -74,7 +74,7 @@
     "madge": "^6.1.0",
     "mocha": "^10.2.0",
     "nyc": "^15.1.0",
-    "prettier": "^3.1.1",
+    "prettier": "^3.2.4",
     "shx": "^0.3.4",
     "sinon": "^16.1.3",
     "ts-node": "^10.9.2",