oclif (https://oclif.io/) related utilities

With this utility library, you will be able to:

• Print out pretty full help/usage information
• Reconstruct the full command line as a string
• Insert help/usage information into README.md file automatically

This library has been verified to be working with @oclif/core v2 and v3, you just need to add it as a dependency:

npm install @handy-common-utils/oclif-utils@latest

If the versions of oclif components you are using are older (For example, @oclif/core@1.9.0, @oclif/plugin-plugins@2.1.0, @oclif/plugin-help@5.1.12, oclif@3.0.1), you need to use version 1.1.3 of this package. Or if you are using really old versions of oclif components (that means you are still using @oclif/config, @oclif/command, @oclif/parser), you need to use version 1.0.9 of this package.

The function withEnhancedFlagsHandled(...) checks whether '-h' or '--help' is the only command line argument. If that is the case, it will build the help information, print it out, then exit with exit code 0. In such case, your command processing code after it won't get executed.

To use it, just need to add this as the first line in the run() function of your command class:

const options = await withEnhancedFlagsHandled(this, () => this.parse(<Your command class name>));

And, the --help/-h flag needs to be defined, like this:

static flags = {
  ...enhancedFlags,
  // your other flags
};

Below is a full example:

import { Command, Flags } from '@oclif/core'
import { enhancedFlags, withEnhancedFlagsHandled } from '@handy-common-utils/oclif-utils';

class Hello extends Command {
  // Feel free to define description, examples, etc.
  // They will be printed out as part of the help/usage information.

  static flags = {
    ...enhancedFlags,
    // and other flags ...
  }

  // and args ...

  async run(): Promise<void> {
    const options = await withEnhancedFlagsHandled(this, () => this.parse(Hello));

    // your command processing code ...
  }
}

Sometimes it would be useful to record or print out the full command line. The reconstructCommandLine(...) can return a string containing the full command line.

Below is an example:

import { Command, Flags } from '@oclif/core'
import { reconstructCommandLine, withEnhancedFlagsHandled } from '@handy-common-utils/oclif-utils';

class Hello extends Command {
  // other code ...

  async run(): Promise<void> {
    const options = await withEnhancedFlagsHandled(this, () => this.parse(Hello));
    const fullCommandLine = reconstructCommandLine(this, options);

    // your command processing code ...
  }
}

In many occasions it would be handy if help/usage information can be inserted into README.md automatically. This can be achieved in two steps.

Step 1: Add --update-readme.md support in your command

As long as enhancedFlags and withEnhancedFlagsHandled(...) are used, then --update-readme.md is supported automatically. See the examples above for details.

Step 2: Run ./bin/run --update-readme.md as part of your workflow

In your CI/CD workflow, you can just run your command with --update-readme.md, then the command will update README.md automatically. You may want to commit the change to README.md after it is updated.

Below are example scripts in package.json:

  "scripts": {
    "preversion": "./bin/run --update-readme.md && git add README.md"
  },

Ƭ CommandOptions<C>: C extends Input<infer _F, infer _B, infer _A> ? Awaited<ParsedOutput<FBA<C>>> : never

Typical usage: CommandOptions<typeof YourCommand>

• Const enhancedFlags: Object

Flags of '--help'/'-h' and '--update-readme.md'

▸ generateHelpText<T>(commandInstance, options?): Promise<string>

Generate formatted text content of help to a command

Promise<string>

help content

▸ injectHelpTextIntoReadmeMd<T>(commandInstance, options?): Promise<void>

Replace the help text in the README.md file. Help text is marked by <!-- help start --> and <!-- help end -->.

Promise<void>

void

▸ reconstructCommandLine<T>(commandInstance, options): string

Reconstruct the command line from already parsed options.

string

the command line string corresponding to the parsed options

▸ withEnhancedFlagsHandled<T, O>(commandInstance, parse, helpOptions?, additionalHandler?): Promise<O>

Parse command line arguments, with enhanced flags handled

Promise<O>

Output from 'this.parse()'.

Throws

Error if the command line arguments are considered invalid by 'this.parse()'.