oclif 4.4.21 → 4.5.0

package/README.md

@@ -1,26 +1,26 @@
-
 <img src="https://user-images.githubusercontent.com/449385/38243295-e0a47d58-372e-11e8-9bc0-8c02a6f4d2ac.png" width="260" height="73">
 
-
-oclif: Node.JS Open CLI Framework
-=================================
+# oclif: Node.JS Open CLI Framework
 
 [![Version](https://img.shields.io/npm/v/oclif.svg)](https://npmjs.org/package/oclif)
 [![Downloads/week](https://img.shields.io/npm/dw/@oclif/command.svg)](https://npmjs.org/package/@oclif/core)
 [![License](https://img.shields.io/npm/l/oclif.svg)](https://github.com/oclif/oclif/blob/main/package.json)
 
 <!-- toc -->
-* [🗒 Description](#-description)
-* [🚀 Getting Started Tutorial](#-getting-started-tutorial)
-* [✨ Features](#-features)
-* [📌 Requirements](#-requirements)
-* [📌 Migrating from V1](#-migrating-from-v1)
-* [🏗 Usage](#-usage)
-* [📚 Examples](#-examples)
-* [🔨 Commands](#-commands)
-* [🏭 Related Repositories](#-related-repositories)
-* [🦔 Learn More](#-learn-more)
-* [📣 Feedback](#-feedback)
+
+- [oclif: Node.JS Open CLI Framework](#oclif-nodejs-open-cli-framework)
+- [🗒 Description](#-description)
+- [🚀 Getting Started Tutorial](#-getting-started-tutorial)
+- [✨ Features](#-features)
+- [📌 Requirements](#-requirements)
+- [📌 Migrating from V1](#-migrating-from-v1)
+- [🏗 Usage](#-usage)
+- [📚 Examples](#-examples)
+- [🔨 Commands](#-commands)
+- [Command Topics](#command-topics)
+- [🏭 Related Repositories](#-related-repositories)
+- [🦔 Learn More](#-learn-more)
+- [📣 Feedback](#-feedback)
 <!-- tocstop -->
 
 # 🗒 Description
@@ -35,17 +35,17 @@ The [Getting Started tutorial](http://oclif.io/docs/introduction) is a step-by-s
 
 # ✨ Features
 
-* **Flag/Argument parsing** - No CLI framework would be complete without a flag parser. We've built a custom one from years of experimentation that we feel consistently handles user input flexible enough for the user to be able to use the CLI in ways they expect, but without compromising strictness guarantees to the developer.
-* **Super Speed** - The overhead for running an oclif CLI command is almost nothing. [It requires very few dependencies](https://www.npmjs.com/package/@oclif/command?activeTab=dependencies) (only 35 dependencies in a minimal setup—including all transitive dependencies). Also, only the command to be executed will be required with node. So large CLIs with many commands will load equally as fast as a small one with a single command.
-* **CLI Generator** - Run a single command to scaffold out a fully functional CLI and get started quickly. See [Usage](#-usage) below.
-* **Testing Helpers** - We've put a lot of work into making commands easier to test and mock out stdout/stderr. The generator will automatically create [scaffolded tests](https://github.com/oclif/hello-world/blob/main/test/commands/hello.test.ts).
-* **Auto-documentation** - By default you can pass `--help` to the CLI to get help such as flag options and argument information. This information is also automatically placed in the README whenever the npm package of the CLI is published. See the [multi-command CLI example](https://github.com/oclif/example-multi-ts)
-* **Plugins** - Using [plugins](https://oclif.io/docs/plugins), users of the CLI can extend it with new functionality, a CLI can be split into modular components, and functionality can be shared amongst multiple CLIs. See [Building your own plugin](https://oclif.io/docs/plugins#building-your-own-plugin).
-* **Hooks** - Use lifecycle hooks to run functionality any time a CLI starts, or on custom triggers. Use this whenever custom functionality needs to be shared between various components of the CLI.
-* **TypeScript** - Everything in the core of oclif is written in TypeScript and the generator will build fully configured TypeScript CLIs. If you use plugins support, the CLI will automatically use `ts-node` to run the plugins enabling you to use TypeScript with minimal-to-no boilerplate needed for any oclif CLI.
-* **Auto-updating Installers** - oclif can package your CLI into [different installers](https://oclif.io/docs/releasing) that will not require the user to already have node installed on the machine. These can be made auto-updatable by using [plugin-update](https://github.com/oclif/plugin-update).
-* **Everything is Customizable** - Pretty much anything can be swapped out and replaced inside oclif if needed—including the arg/flag parser.
-* **Autocomplete** - Automatically include autocomplete for your CLI. This includes not only command names and flag names, but flag values as well. For example, it's possible to configure the Heroku CLI to have completions for Heroku app names:
+- **Flag/Argument parsing** - No CLI framework would be complete without a flag parser. We've built a custom one from years of experimentation that we feel consistently handles user input flexible enough for the user to be able to use the CLI in ways they expect, but without compromising strictness guarantees to the developer.
+- **Super Speed** - The overhead for running an oclif CLI command is almost nothing. [It requires very few dependencies](https://www.npmjs.com/package/@oclif/command?activeTab=dependencies) (only 35 dependencies in a minimal setup—including all transitive dependencies). Also, only the command to be executed will be required with node. So large CLIs with many commands will load equally as fast as a small one with a single command.
+- **CLI Generator** - Run a single command to scaffold out a fully functional CLI and get started quickly. See [Usage](#-usage) below.
+- **Testing Helpers** - We've put a lot of work into making commands easier to test and mock out stdout/stderr. The generator will automatically create [scaffolded tests](https://github.com/oclif/hello-world/blob/main/test/commands/hello.test.ts).
+- **Auto-documentation** - By default you can pass `--help` to the CLI to get help such as flag options and argument information. This information is also automatically placed in the README whenever the npm package of the CLI is published. See the [multi-command CLI example](https://github.com/oclif/example-multi-ts)
+- **Plugins** - Using [plugins](https://oclif.io/docs/plugins), users of the CLI can extend it with new functionality, a CLI can be split into modular components, and functionality can be shared amongst multiple CLIs. See [Building your own plugin](https://oclif.io/docs/plugins#building-your-own-plugin).
+- **Hooks** - Use lifecycle hooks to run functionality any time a CLI starts, or on custom triggers. Use this whenever custom functionality needs to be shared between various components of the CLI.
+- **TypeScript** - Everything in the core of oclif is written in TypeScript and the generator will build fully configured TypeScript CLIs. If you use plugins support, the CLI will automatically use `ts-node` to run the plugins enabling you to use TypeScript with minimal-to-no boilerplate needed for any oclif CLI.
+- **Auto-updating Installers** - oclif can package your CLI into [different installers](https://oclif.io/docs/releasing) that will not require the user to already have node installed on the machine. These can be made auto-updatable by using [plugin-update](https://github.com/oclif/plugin-update).
+- **Everything is Customizable** - Pretty much anything can be swapped out and replaced inside oclif if needed—including the arg/flag parser.
+- **Autocomplete** - Automatically include autocomplete for your CLI. This includes not only command names and flag names, but flag values as well. For example, it's possible to configure the Heroku CLI to have completions for Heroku app names:
 
 ```
 $ heroku info --app=<tab><tab> # will complete with all the Heroku apps a user has in their account
@@ -69,6 +69,7 @@ If you have been using version 1 of the [`oclif` CLI](https://github.com/oclif/o
 ## New Commands
 
 Version 2 now includes all the commands from the [`oclif-dev` CLI](https://github.com/oclif/dev-cli). This means that you can now use a single CLI for all your oclif needs. These commands include:
+
 - `oclif manifest`
 - `oclif pack`
 - `oclif pack:deb`
@@ -80,7 +81,6 @@ Version 2 now includes all the commands from the [`oclif-dev` CLI](https://githu
 - `oclif upload:win` (formerly known as `oclif-dev publish:win`)
 - `oclif readme`
 
-
 # 🏗 Usage
 
 Creating a CLI:
@@ -105,330 +105,36 @@ hello world! (./src/commands/hello/world.ts)
 
 # 📚 Examples
 
-* [Hello-World](https://github.com/oclif/hello-world)
-* [Salesforce CLI](https://github.com/salesforcecli/cli)
-* [Heroku CLI](https://github.com/heroku/cli)
+- [Hello-World](https://github.com/oclif/hello-world)
+- [Salesforce CLI](https://github.com/salesforcecli/cli)
+- [Heroku CLI](https://github.com/heroku/cli)
 
 # 🔨 Commands
 
 <!-- commands -->
-* [`oclif generate NAME`](#oclif-generate-name)
-* [`oclif generate command NAME`](#oclif-generate-command-name)
-* [`oclif generate hook NAME`](#oclif-generate-hook-name)
-* [`oclif help [COMMAND]`](#oclif-help-command)
-* [`oclif manifest [PATH]`](#oclif-manifest-path)
-* [`oclif pack deb`](#oclif-pack-deb)
-* [`oclif pack macos`](#oclif-pack-macos)
-* [`oclif pack tarballs`](#oclif-pack-tarballs)
-* [`oclif pack win`](#oclif-pack-win)
-* [`oclif promote`](#oclif-promote)
-* [`oclif readme`](#oclif-readme)
-* [`oclif upload deb`](#oclif-upload-deb)
-* [`oclif upload macos`](#oclif-upload-macos)
-* [`oclif upload tarballs`](#oclif-upload-tarballs)
-* [`oclif upload win`](#oclif-upload-win)
-
-## `oclif generate NAME`
-
-generate a new CLI
-
-```
-USAGE
-  $ oclif generate [NAME]
-
-ARGUMENTS
-  NAME  directory name of new project
-
-DESCRIPTION
-  generate a new CLI
-
-  This will clone the template repo 'oclif/hello-world' and update package properties
-```
-
-_See code: [src/commands/generate.ts](https://github.com/oclif/oclif/blob/v3.2.1/src/commands/generate.ts)_
-
-## `oclif generate command NAME`
-
-add a command to an existing CLI or plugin
-
-```
-USAGE
-  $ oclif generate command [NAME] [--force]
-
-ARGUMENTS
-  NAME  name of command
-
-FLAGS
-  --force  overwrite existing files
-
-DESCRIPTION
-  add a command to an existing CLI or plugin
-```
-
-## `oclif generate hook NAME`
-
-add a hook to an existing CLI or plugin
-
-```
-USAGE
-  $ oclif generate hook [NAME] [--force] [--event <value>]
-
-ARGUMENTS
-  NAME  name of hook (snake_case)
-
-FLAGS
-  --event=<value>  [default: init] event to run hook on
-  --force          overwrite existing files
-
-DESCRIPTION
-  add a hook to an existing CLI or plugin
-```
-
-## `oclif help [COMMAND]`
-
-Display help for oclif.
-
-```
-USAGE
-  $ oclif help [COMMAND] [-n]
-
-ARGUMENTS
-  COMMAND  Command to show help for.
-
-FLAGS
-  -n, --nested-commands  Include all nested commands in the output.
-
-DESCRIPTION
-  Display help for oclif.
-```
-
-_See code: [@oclif/plugin-help](https://github.com/oclif/plugin-help/blob/v5.1.12/src/commands/help.ts)_
-
-## `oclif manifest [PATH]`
-
-generates plugin manifest json
-
-```
-USAGE
-  $ oclif manifest [PATH]
-
-ARGUMENTS
-  PATH  [default: .] path to plugin
-
-DESCRIPTION
-  generates plugin manifest json
-```
-
-_See code: [src/commands/manifest.ts](https://github.com/oclif/oclif/blob/v3.2.1/src/commands/manifest.ts)_
-
-## `oclif pack deb`
-
-pack CLI into debian package
-
-```
-USAGE
-  $ oclif pack deb -r <value> [-t <value>]
-
-FLAGS
-  -r, --root=<value>     (required) [default: .] path to oclif CLI root
-  -t, --tarball=<value>  optionally specify a path to a tarball already generated by NPM
-  -Z, --compression=<value> optionally override compression, see output of
-                            'dpkg-deb --help' in the -Z description for valid options.
-
-DESCRIPTION
-  pack CLI into debian package
-```
-
-## `oclif pack macos`
-
-pack CLI into macOS .pkg
-
-```
-USAGE
-  $ oclif pack macos -r <value> [-t <value>]
-
-FLAGS
-  -r, --root=<value>     (required) [default: .] path to oclif CLI root
-  -t, --tarball=<value>  optionally specify a path to a tarball already generated by NPM
-
-DESCRIPTION
-  pack CLI into macOS .pkg
-```
-
-## `oclif pack tarballs`
-
-packages oclif CLI into tarballs
 
-```
-USAGE
-  $ oclif pack tarballs -r <value> [-t <value>] [--xz] [--parallel] [-l <value>]
-
-FLAGS
-  -l, --tarball=<value>  optionally specify a path to a tarball already generated by NPM
-  -r, --root=<value>     (required) [default: .] path to oclif CLI root
-  -t, --targets=<value>  comma-separated targets to pack (e.g.: linux-arm,win32-x64)
-  --parallel             build tarballs in parallel
-  --[no-]xz              also build xz
-
-DESCRIPTION
-  packages oclif CLI into tarballs
-
-  This can be used to create oclif CLIs that use the system node or that come preloaded with a node binary.
-```
-
-## `oclif pack win`
-
-create windows installer from oclif CLI
-
-```
-USAGE
-  $ oclif pack win -r <value> [-t <value>]
-
-FLAGS
-  -r, --root=<value>     (required) [default: .] path to oclif CLI root
-  -t, --tarball=<value>  optionally specify a path to a tarball already generated by NPM
-
-DESCRIPTION
-  create windows installer from oclif CLI
-
-  This command requires WINDOWS_SIGNING (prefixed with the name of your executable, e.g. OCLIF_WINDOWS_SIGNING_PASS) to
-  be set in the environment
-```
-
-## `oclif promote`
-
-promote CLI builds to a S3 release channel
-
-```
-USAGE
-  $ oclif promote -r <value> --version <value> --sha <value> --channel <value> [-t <value>] [-d] [-m] [-w]
-    [-a <value>] [--xz] [--indexes]
-
-FLAGS
-  -a, --max-age=<value>  [default: 86400] cache control max-age in seconds
-  -d, --deb              promote debian artifacts
-  -m, --macos            promote macOS pkg
-  -r, --root=<value>     (required) [default: .] path to the oclif CLI project root
-  -t, --targets=<value>  comma-separated targets to promote (e.g.: linux-arm,win32-x64)
-  -w, --win              promote Windows exe
-  --channel=<value>      (required) [default: stable] which channel to promote to
-  --indexes              append the promoted urls into the index files
-  --sha=<value>          (required) 7-digit short git commit SHA of the CLI to promote
-  --version=<value>      (required) semantic version of the CLI to promote
-  --[no-]xz              also upload xz
-
-DESCRIPTION
-  promote CLI builds to a S3 release channel
-```
-
-_See code: [src/commands/promote.ts](https://github.com/oclif/oclif/blob/v3.2.1/src/commands/promote.ts)_
-
-## `oclif readme`
-
-adds commands to README.md in current directory
-
-```
-USAGE
-  $ oclif readme --dir <value> [--multi] [--aliases]
-
-FLAGS
-  --[no-]aliases  include aliases in the command list
-  --dir=<value>   (required) [default: docs] output directory for multi docs
-  --multi         create a different markdown page for each topic
-
-DESCRIPTION
-  adds commands to README.md in current directory
-
-  The readme must have any of the following tags inside of it for it to be replaced or else it will do nothing:
-
-  # Usage
-
-  <!-- usage -->
-
-  # Commands
-
-  <!-- commands -->
+# Command Topics
 
-  Customize the code URL prefix by setting oclif.repositoryPrefix in package.json.
-```
-
-_See code: [src/commands/readme.ts](https://github.com/oclif/oclif/blob/v3.2.1/src/commands/readme.ts)_
-
-## `oclif upload deb`
-
-upload deb package built with pack:deb
-
-```
-USAGE
-  $ oclif upload deb -r <value>
-
-FLAGS
-  -r, --root=<value>  (required) [default: .] path to oclif CLI root
-
-DESCRIPTION
-  upload deb package built with pack:deb
-```
-
-## `oclif upload macos`
-
-upload macos installers built with pack:macos
-
-```
-USAGE
-  $ oclif upload macos -r <value>
-
-FLAGS
-  -r, --root=<value>  (required) [default: .] path to oclif CLI root
-
-DESCRIPTION
-  upload macos installers built with pack:macos
-```
-
-## `oclif upload tarballs`
-
-upload an oclif CLI to S3
+- [`oclif generate`](docs/generate.md) - generate a new CLI
+- [`oclif help`](docs/help.md) - Display help for oclif.
+- [`oclif manifest`](docs/manifest.md) - generates plugin manifest json
+- [`oclif pack`](docs/pack.md) - package an oclif CLI into installable artifacts
+- [`oclif promote`](docs/promote.md) - promote CLI builds to a S3 release channel
+- [`oclif readme`](docs/readme.md) - adds commands to README.md in current directory
+- [`oclif upload`](docs/upload.md) - upload installable CLI artifacts to AWS S3
 
-```
-USAGE
-  $ oclif upload tarballs -r <value> [-t <value>] [--xz]
-
-FLAGS
-  -r, --root=<value>     (required) [default: .] path to oclif CLI root
-  -t, --targets=<value>  comma-separated targets to upload (e.g.: linux-arm,win32-x64)
-  --[no-]xz              also upload xz
-
-DESCRIPTION
-  upload an oclif CLI to S3
-
-  "aws-sdk" will need to be installed as a devDependency to upload.
-```
-
-## `oclif upload win`
-
-upload windows installers built with pack:win
-
-```
-USAGE
-  $ oclif upload win -r <value>
-
-FLAGS
-  -r, --root=<value>  (required) [default: .] path to oclif CLI root
-
-DESCRIPTION
-  upload windows installers built with pack:win
-```
 <!-- commandsstop -->
 
 # 🏭 Related Repositories
 
-* [@oclif/core](https://github.com/oclif/core) - Base library for oclif. This can be used directly without the generator.
-* [@oclif/cli-ux](https://github.com/oclif/cli-ux) - Library for common CLI UI utilities.
-* [@oclif/test](https://github.com/oclif/test) - Test helper for oclif.
+- [@oclif/core](https://github.com/oclif/core) - Base library for oclif. This can be used directly without the generator.
+- [@oclif/cli-ux](https://github.com/oclif/cli-ux) - Library for common CLI UI utilities.
+- [@oclif/test](https://github.com/oclif/test) - Test helper for oclif.
 
 # 🦔 Learn More
 
-* [Salesforce Release Announcement](https://engineering.salesforce.com/open-sourcing-oclif-the-cli-framework-that-powers-our-clis-21fbda99d33a)
-* [Heroku Release Announcement](https://blog.heroku.com/open-cli-framework)
+- [Salesforce Release Announcement](https://engineering.salesforce.com/open-sourcing-oclif-the-cli-framework-that-powers-our-clis-21fbda99d33a)
+- [Heroku Release Announcement](https://blog.heroku.com/open-cli-framework)
 
 # 📣 Feedback
 

package/lib/commands/pack/macos.js

@@ -230,7 +230,6 @@ the CLI should already exist in a directory named after the CLI that is the root
                 '--scripts',
                 scriptsDir,
             ];
-            /* eslint-enable array-element-newline */
             if (macos.sign) {
                 args.push('--sign', macos.sign);
             }

package/lib/commands/readme.d.ts

@@ -3,8 +3,10 @@ export default class Readme extends Command {
     static description: string;
     static flags: {
         aliases: Interfaces.BooleanFlag<boolean>;
-        dir: Interfaces.OptionFlag<string, Interfaces.CustomOptions>;
         multi: Interfaces.BooleanFlag<boolean>;
+        'nested-topics-depth': Interfaces.OptionFlag<number | undefined, Interfaces.CustomOptions>;
+        'output-dir': Interfaces.OptionFlag<string, Interfaces.CustomOptions>;
+        'plugin-directory': Interfaces.OptionFlag<string | undefined, Interfaces.CustomOptions>;
         'readme-path': Interfaces.OptionFlag<string, Interfaces.CustomOptions>;
         'repository-prefix': Interfaces.OptionFlag<string | undefined, Interfaces.CustomOptions>;
         version: Interfaces.OptionFlag<string | undefined, Interfaces.CustomOptions>;
@@ -14,7 +16,7 @@ export default class Readme extends Command {
     commandCode(config: Interfaces.Config, c: Command.Cached): string | undefined;
     commands(config: Interfaces.Config, commands: Command.Cached[]): string;
     createTopicFile(file: string, config: Interfaces.Config, topic: Interfaces.Topic, commands: Command.Cached[]): void;
-    multiCommands(config: Interfaces.Config, commands: Command.Cached[], dir: string): string;
+    multiCommands(config: Interfaces.Config, commands: Command.Cached[], dir: string, nestedTopicsDepth: number | undefined): string;
     renderCommand(config: Interfaces.Config, c: Command.Cached): string;
     replaceTag(readme: string, tag: string, body: string): string;
     run(): Promise<void>;

package/lib/commands/readme.js

@@ -46,13 +46,37 @@ The readme must have any of the following tags inside of it for it to be replace
 Customize the code URL prefix by setting oclif.repositoryPrefix in package.json.
 `;
     static flags = {
-        aliases: core_1.Flags.boolean({ allowNo: true, default: true, description: 'include aliases in the command list' }),
-        dir: core_1.Flags.string({ default: 'docs', description: 'output directory for multi docs', required: true }),
-        multi: core_1.Flags.boolean({ description: 'create a different markdown page for each topic' }),
-        'readme-path': core_1.Flags.string({ default: 'README.md', description: 'Path to the README file.', required: true }),
-        'repository-prefix': core_1.Flags.string({ description: 'a template string used to build links to the source code' }),
+        aliases: core_1.Flags.boolean({
+            allowNo: true,
+            default: true,
+            description: 'Include aliases in the command list.',
+        }),
+        multi: core_1.Flags.boolean({
+            description: 'Create a different markdown page for each topic.',
+        }),
+        'nested-topics-depth': core_1.Flags.integer({
+            dependsOn: ['multi'],
+            description: 'Max nested topics depth for multi markdown page generation. Use with --multi enabled.',
+        }),
+        'output-dir': core_1.Flags.string({
+            aliases: ['dir'],
+            default: 'docs',
+            description: 'Output directory for multi docs.',
+            required: true,
+        }),
+        'plugin-directory': core_1.Flags.string({
+            description: 'Plugin directory to generate README for. Defaults to the current directory.',
+        }),
+        'readme-path': core_1.Flags.string({
+            default: 'README.md',
+            description: 'Path to the README file.',
+            required: true,
+        }),
+        'repository-prefix': core_1.Flags.string({
+            description: 'A template string used to build links to the source code.',
+        }),
         version: core_1.Flags.string({
-            description: 'version to use in readme links. defaults to the version in package.json',
+            description: 'Version to use in readme links. Defaults to the version in package.json.',
         }),
     };
     flags;
@@ -90,7 +114,7 @@ Customize the code URL prefix by setting oclif.repositoryPrefix in package.json.
                     : `* [\`${config.bin}\`](#${slugify.slug(`${config.bin}`)})`;
             }),
             '',
-            ...commands.map((c) => this.renderCommand(config, c)).map((s) => s.trim() + '\n'),
+            ...commands.map((c) => this.renderCommand(config, { ...c })).map((s) => s.trim() + '\n'),
         ]
             .join('\n')
             .trim();
@@ -107,11 +131,13 @@ Customize the code URL prefix by setting oclif.repositoryPrefix in package.json.
         ]
             .join('\n')
             .trim() + '\n';
-        fs.outputFileSync(file, doc);
+        fs.outputFileSync(path.resolve(this.flags['plugin-directory'] ?? process.cwd(), file), doc);
     }
-    multiCommands(config, commands, dir) {
+    multiCommands(config, commands, dir, nestedTopicsDepth) {
         let topics = config.topics;
-        topics = topics.filter((t) => !t.hidden && !t.name.includes(':'));
+        topics = nestedTopicsDepth
+            ? topics.filter((t) => !t.hidden && (t.name.match(/:/g) || []).length < nestedTopicsDepth)
+            : topics.filter((t) => !t.hidden && !t.name.includes(':'));
         topics = topics.filter((t) => commands.find((c) => c.id.startsWith(t.name)));
         topics = (0, util_1.sortBy)(topics, (t) => t.name);
         topics = (0, util_1.uniqBy)(topics, (t) => t.name);
@@ -121,7 +147,7 @@ Customize the code URL prefix by setting oclif.repositoryPrefix in package.json.
         return ([
             '# Command Topics\n',
             ...topics.map((t) => (0, util_1.compact)([
-                `* [\`${config.bin} ${t.name}\`](${dir}/${t.name.replaceAll(':', '/')}.md)`,
+                `* [\`${config.bin} ${t.name.replaceAll(':', config.topicSeparator)}\`](${dir}/${t.name.replaceAll(':', '/')}.md)`,
                 (0, util_1.template)({ config })(t.description || '')
                     .trim()
                     .split('\n')[0],
@@ -169,18 +195,22 @@ Customize the code URL prefix by setting oclif.repositoryPrefix in package.json.
     async run() {
         const { flags } = await this.parse(Readme);
         this.flags = flags;
-        const cwd = process.cwd();
-        const readmePath = path.resolve(cwd, flags['readme-path']);
-        const tsConfigPath = path.resolve(cwd, 'tsconfig.json');
+        this.flags['plugin-directory'] ??= process.cwd();
+        const readmePath = path.resolve(this.flags['plugin-directory'], flags['readme-path']);
+        const tsConfigPath = path.resolve(this.flags['plugin-directory'], 'tsconfig.json');
         const tsConfig = await fs.readJSON(tsConfigPath).catch(() => ({}));
         const outDir = tsConfig.compilerOptions?.outDir ?? 'lib';
         if (!(await fs.pathExists(outDir))) {
             this.warn(`No compiled source found at ${outDir}. Some commands may be missing.`);
         }
-        const config = await core_1.Config.load({ devPlugins: false, root: cwd, userPlugins: false });
+        const config = await core_1.Config.load({
+            devPlugins: false,
+            root: this.flags['plugin-directory'],
+            userPlugins: false,
+        });
         try {
             // eslint-disable-next-line node/no-missing-require
-            const p = require.resolve('@oclif/plugin-legacy', { paths: [cwd] });
+            const p = require.resolve('@oclif/plugin-legacy', { paths: [this.flags['plugin-directory']] });
             const plugin = new core_1.Plugin({ root: p, type: 'core' });
             await plugin.load();
             config.plugins.set(plugin.name, plugin);
@@ -197,7 +227,9 @@ Customize the code URL prefix by setting oclif.repositoryPrefix in package.json.
         commands = (0, util_1.uniqBy)(commands, (c) => c.id);
         commands = (0, util_1.sortBy)(commands, (c) => c.id);
         readme = this.replaceTag(readme, 'usage', this.usage(config));
-        readme = this.replaceTag(readme, 'commands', this.flags.multi ? this.multiCommands(config, commands, this.flags.dir) : this.commands(config, commands));
+        readme = this.replaceTag(readme, 'commands', flags.multi
+            ? this.multiCommands(config, commands, flags['output-dir'], flags['nested-topics-depth'])
+            : this.commands(config, commands));
         readme = this.replaceTag(readme, 'toc', this.toc(config, readme));
         readme = readme.trimEnd();
         readme += '\n';
@@ -234,7 +266,13 @@ USAGE
      * fetches the path to a command
      */
     commandPath(plugin, c) {
-        const commandsDir = plugin.pjson.oclif.commands;
+        const strategy = typeof plugin.pjson.oclif?.commands === 'string' ? 'pattern' : plugin.pjson.oclif?.commands?.strategy;
+        // if the strategy is explicit, we can't determine the path so return undefined
+        if (strategy === 'explicit')
+            return;
+        const commandsDir = typeof plugin.pjson.oclif?.commands === 'string'
+            ? plugin.pjson.oclif?.commands
+            : plugin.pjson.oclif?.commands?.target;
         if (!commandsDir)
             return;
         const hasTypescript = plugin.pjson.devDependencies?.typescript || plugin.pjson.dependencies?.typescript;

package/lib/generators/cli.js

@@ -29,6 +29,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 const node_child_process_1 = require("node:child_process");
 const fs = __importStar(require("node:fs"));
 const path = __importStar(require("node:path"));
+const validate_npm_package_name_1 = __importDefault(require("validate-npm-package-name"));
 const yeoman_generator_1 = __importDefault(require("yeoman-generator"));
 const util_1 = require("../util");
 const debug = require('debug')('generator-oclif');
@@ -143,12 +144,14 @@ class CLI extends yeoman_generator_1.default {
                     message: 'npm package name',
                     name: 'name',
                     type: 'input',
+                    validate: (d) => (0, validate_npm_package_name_1.default)(d).validForNewPackages || 'Invalid package name',
                 },
                 {
                     default: (answers) => answers.name,
                     message: 'command bin name the CLI will export',
                     name: 'bin',
                     type: 'input',
+                    validate: (d) => (0, util_1.validateBin)(d) || 'Invalid bin name',
                 },
                 {
                     default: defaults.description,

package/lib/util.d.ts

@@ -13,4 +13,5 @@ export declare const prettifyPaths: (input: unknown) => string;
 export declare const hash: (algo: string, fp: string | string[]) => Promise<string>;
 export declare function checkFor7Zip(): Promise<void>;
 export declare function isEmpty(obj: Record<string, unknown>): boolean;
+export declare function validateBin(bin: string): boolean;
 export {};

package/lib/util.js

@@ -23,7 +23,7 @@ var __importStar = (this && this.__importStar) || function (mod) {
     return result;
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.isEmpty = exports.checkFor7Zip = exports.hash = exports.prettifyPaths = exports.sortVersionsObjectByKeysDesc = exports.template = exports.sortBy = exports.uniq = exports.compact = exports.uniqBy = exports.castArray = void 0;
+exports.validateBin = exports.isEmpty = exports.checkFor7Zip = exports.hash = exports.prettifyPaths = exports.sortVersionsObjectByKeysDesc = exports.template = exports.sortBy = exports.uniq = exports.compact = exports.uniqBy = exports.castArray = void 0;
 const core_1 = require("@oclif/core");
 const node_child_process_1 = require("node:child_process");
 const crypto = __importStar(require("node:crypto"));
@@ -139,3 +139,7 @@ function isEmpty(obj) {
     return Object.keys(obj).length === 0;
 }
 exports.isEmpty = isEmpty;
+function validateBin(bin) {
+    return /^[\w-]+$/.test(bin);
+}
+exports.validateBin = validateBin;

package/oclif.manifest.json

@@ -203,25 +203,45 @@
       "description": "adds commands to README.md in current directory\nThe readme must have any of the following tags inside of it for it to be replaced or else it will do nothing:\n# Usage\n<!-- usage -->\n# Commands\n<!-- commands -->\n# Table of contents\n<!-- toc -->\n\nCustomize the code URL prefix by setting oclif.repositoryPrefix in package.json.\n",
       "flags": {
         "aliases": {
-          "description": "include aliases in the command list",
+          "description": "Include aliases in the command list.",
           "name": "aliases",
           "allowNo": true,
           "type": "boolean"
         },
-        "dir": {
-          "description": "output directory for multi docs",
-          "name": "dir",
+        "multi": {
+          "description": "Create a different markdown page for each topic.",
+          "name": "multi",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "nested-topics-depth": {
+          "dependsOn": [
+            "multi"
+          ],
+          "description": "Max nested topics depth for multi markdown page generation. Use with --multi enabled.",
+          "name": "nested-topics-depth",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "output-dir": {
+          "aliases": [
+            "dir"
+          ],
+          "description": "Output directory for multi docs.",
+          "name": "output-dir",
           "required": true,
           "default": "docs",
           "hasDynamicHelp": false,
           "multiple": false,
           "type": "option"
         },
-        "multi": {
-          "description": "create a different markdown page for each topic",
-          "name": "multi",
-          "allowNo": false,
-          "type": "boolean"
+        "plugin-directory": {
+          "description": "Plugin directory to generate README for. Defaults to the current directory.",
+          "name": "plugin-directory",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
         },
         "readme-path": {
           "description": "Path to the README file.",
@@ -233,14 +253,14 @@
           "type": "option"
         },
         "repository-prefix": {
-          "description": "a template string used to build links to the source code",
+          "description": "A template string used to build links to the source code.",
           "name": "repository-prefix",
           "hasDynamicHelp": false,
           "multiple": false,
           "type": "option"
         },
         "version": {
-          "description": "version to use in readme links. defaults to the version in package.json",
+          "description": "Version to use in readme links. Defaults to the version in package.json.",
           "name": "version",
           "hasDynamicHelp": false,
           "multiple": false,
@@ -737,5 +757,5 @@
       ]
     }
   },
-  "version": "4.4.21"
+  "version": "4.5.0"
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "oclif",
   "description": "oclif: create your own CLI",
-  "version": "4.4.21",
+  "version": "4.5.0",
   "author": "Salesforce",
   "bin": {
     "oclif": "bin/run.js"
@@ -10,7 +10,7 @@
   "dependencies": {
     "@aws-sdk/client-cloudfront": "^3.525.0",
     "@aws-sdk/client-s3": "^3.515.0",
-    "@oclif/core": "^3.19.2",
+    "@oclif/core": "^3.21.0",
     "@oclif/plugin-help": "^6.0.14",
     "@oclif/plugin-not-found": "^3.0.10",
     "@oclif/plugin-warn-if-update-available": "^3.0.12",
@@ -25,11 +25,12 @@
     "normalize-package-data": "^3.0.3",
     "semver": "^7.6.0",
     "sort-package-json": "^2.8.0",
+    "validate-npm-package-name": "^5.0.0",
     "yeoman-environment": "^3.15.1",
     "yeoman-generator": "^5.8.0"
   },
   "devDependencies": {
-    "@commitlint/config-conventional": "^17.7.0",
+    "@commitlint/config-conventional": "^18",
     "@oclif/plugin-legacy": "^2.0.7",
     "@oclif/prettier-config": "^0.2.1",
     "@oclif/test": "^3.1.13",
@@ -43,19 +44,18 @@
     "@types/node": "^18",
     "@types/semver": "^7.5.7",
     "@types/shelljs": "^0.8.11",
+    "@types/validate-npm-package-name": "^4.0.2",
     "@types/yeoman-generator": "^5.2.11",
     "chai": "^4.4.1",
-    "commitlint": "^17.7.2",
-    "conventional-changelog-cli": "^2.2.2",
+    "commitlint": "^18",
     "eslint": "^8.57.0",
-    "eslint-config-oclif": "^5.0.2",
+    "eslint-config-oclif": "^5.0.4",
     "eslint-config-oclif-typescript": "^3.0.48",
     "eslint-config-prettier": "^9.0.0",
     "eslint-plugin-perfectionist": "^2.1.0",
     "fancy-test": "^3.0.11",
-    "globby": "^11.1.0",
-    "husky": "^8.0.3",
-    "lint-staged": "^14.0.1",
+    "husky": "^9",
+    "lint-staged": "^15",
     "lodash.clonedeep": "^4.5.0",
     "mocha": "^10.3.0",
     "nyc": "^15.1.0",
@@ -129,7 +129,7 @@
     "postpack": "shx rm oclif.manifest.json",
     "posttest": "yarn run lint",
     "prepack": "shx rm -rf lib && tsc && bin/run.js manifest .",
-    "prepare": "husky install",
+    "prepare": "husky",
     "test:integration:cli": "mocha test/integration/cli.test.ts --timeout 600000",
     "test:integration:deb": "mocha test/integration/deb.test.ts --timeout 900000",
     "test:integration:macos": "mocha test/integration/macos.test.ts --timeout 900000",