@handy-common-utils/oclif-utils

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

Features

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

Installation

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/[email protected], @oclif/[email protected], @oclif/[email protected], [email protected]), 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.

Usage

Print out full help/usage information

The function withEnhancedFlagsHandled(...) checks whether '-h' or '--help' or '-v' or '--version' is the only command line argument. If that is the case, it will build the help or version 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 ...
  }
}

Print out version information

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

The example in previous section handles '-v' and '--version' too.

Don't use the Flags.version(...) provided by oclif, it is buggy.

Reconstruct the full command line as a string

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 ...
  }
}

Insert help/usage information into README.md

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"
  },

API

Module: oclif-utils

Type Aliases

CommandOptions

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

Typical usage: CommandOptions<typeof YourCommand>

Type parameters

| Name | | :------ | | C |

Variables

enhancedFlags

• Const enhancedFlags: Object

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

Type declaration

| Name | Type | | :------ | :------ | | help | BooleanFlag<boolean> | | update-readme.md | BooleanFlag<boolean> | | version | BooleanFlag<boolean> |

Functions

generateHelpText

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

Generate formatted text content of help to a command

Type parameters

| Name | Type | | :------ | :------ | | T | extends Command |

Parameters

| Name | Type | Description | | :------ | :------ | :------ | | commandInstance | T | instance of the Command | | options? | Partial<HelpOptions> | (optional) format options |

Returns

Promise<string>

help content

injectHelpTextIntoReadmeMd

▸ 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 -->.

Type parameters

| Name | Type | | :------ | :------ | | T | extends Command |

Parameters

| Name | Type | Description | | :------ | :------ | :------ | | commandInstance | T | instance of the Command | | options? | Partial<HelpOptions> | (optional) format options |

Returns

Promise<void>

void

reconstructCommandLine

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

Reconstruct the command line from already parsed options.

Type parameters

| Name | Type | | :------ | :------ | | T | extends (...args: any) => any |

Parameters

| Name | Type | Description | | :------ | :------ | :------ | | commandInstance | InstanceType<T> | When calling from the subclass of Command, just pass this | | options | ParserOutput<FlagOutput, FlagOutput, ArgOutput> | Already parsed options. When calling from the subclass of Command, it is the return value of this.parse(...). |

Returns

string

the command line string corresponding to the parsed options

withEnhancedFlagsHandled

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

Parse command line arguments, with enhanced flags handled

Type parameters

| Name | Type | | :------ | :------ | | T | extends (...args: any) => any | | O | O |

Parameters

| Name | Type | Description | | :------ | :------ | :------ | | commandInstance | InstanceType<T> | Instance of the command class, usually 'this' | | parse | () => Promise<O> | The function to call 'this.parse()| |helpOptions?|Partial\<HelpOptions\> | Optional options to customise the formatting of help text | | additionalHandler? | (commandInstance: InstanceType\<T\>, cliOptions: undefined\|O) => Promise\<void`> | Optional additional handler |

Returns

Promise<O>

Output from 'this.parse()'.

Throws

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