cli-forge 0.10.1 → 0.11.0

package/src/lib/public-api.ts

@@ -0,0 +1,449 @@
+import {
+  type ConfigurationFiles,
+  OptionConfig,
+  OptionConfigToType,
+  ParsedArgs,
+  EnvOptionConfig,
+  ObjectOptionConfig,
+  StringOptionConfig,
+  NumberOptionConfig,
+  BooleanOptionConfig,
+  ArrayOptionConfig,
+  ResolveProperties,
+  AdditionalPropertiesType,
+  WithOptional,
+} from '@cli-forge/parser';
+
+import { InternalCLI } from './internal-cli';
+
+/**
+ * The interface for a CLI application or subcommands.
+ *
+ * {@link cli} is provided as a small helper function to create a new CLI instance.
+ *
+ * @example
+ * ```ts
+ * import { cli } from 'cli-forge';
+ *
+ * cli('basic-cli').command('hello', {
+ *   builder: (args) =>
+ *    args.option('name', {
+ *      type: 'string',
+ *    }),
+ *   handler: (args) => {
+ *     console.log(`Hello, ${args.name}!`);
+ *   }).forge();
+ * ```
+ */
+export interface CLI<TArgs extends ParsedArgs = ParsedArgs> {
+  command<TCommandArgs extends TArgs>(
+    cmd: Command<TArgs, TCommandArgs>
+  ): CLI<TArgs>;
+
+  /**
+   * Registers a new command with the CLI.
+   * @param key What should the new command be called?
+   * @param options Settings for the new command. See {@link CLICommandOptions}.
+   * @returns Updated CLI instance with the new command registered.
+   */
+  command<TCommandArgs extends TArgs>(
+    key: string,
+    options: CLICommandOptions<TArgs, TCommandArgs>
+  ): CLI<TArgs>;
+
+  /**
+   * Registers multiple subcommands with the CLI.
+   * @param commands Several commands to register. Can be the result of a call to {@link cli} or a configuration object.
+   */
+  commands(commands: Command[]): CLI<TArgs>;
+  /**
+   * Registers multiple subcommands with the CLI.
+   * @param commands Several commands to register. Can be the result of a call to {@link cli} or a configuration object.
+   */
+  commands(...commands: Command[]): CLI<TArgs>;
+
+  /**
+   * Register's a configuration provider for the CLI. See {@link ConfigurationProviders} for built-in providers.
+   *
+   * @param provider Provider to register.
+   */
+  config(provider: ConfigurationFiles.ConfigurationProvider<TArgs>): CLI<TArgs>;
+
+  /**
+   * Enables the ability to run CLI commands that contain subcommands as an interactive shell.
+   * This presents as a small shell that only knows the current command and its subcommands.
+   * Any flags already consumed by the command will be passed to every subcommand invocation.
+   */
+  enableInteractiveShell(): CLI<TArgs>;
+
+  /**
+   * Registers a custom global error handler for the CLI. This handler will be called when an error is thrown
+   * during the execution of the CLI and not otherwise handled. Error handlers should re-throw the error if they
+   * cannot handle it, s.t. the next error handler can attempt to handle it.
+   *
+   * @param handler Typically called with an Error object, but you should be prepared to handle any type of error.
+   * @param actions Actions that can be taken by the error handler. Prefer using these over process.exit for better support of interactive shells.
+   */
+  errorHandler(handler: ErrorHandler): CLI<TArgs>;
+
+  /**
+   * Registers a new option for the CLI command. This option will be accessible
+   * within the command handler, as well as any subcommands.
+   *
+   * @param name The name of the option.
+   * @param config Configuration for the option. See {@link UnknownOptionConfig}.
+   * @returns Updated CLI instance with the new option registered.
+   */
+  // Object option overload - must come first for proper contextual typing
+  // Uses direct ObjectOptionConfig type (not `extends`) to ensure TypeScript
+  // infers TProps from `properties` BEFORE evaluating the coerce callback type
+  option<
+    TOption extends string,
+    TCoerce,
+    const TProps extends Record<string, { type: string }>,
+    TAdditionalProps extends false | 'string' | 'number' | 'boolean' = false
+  >(
+    name: TOption,
+    config: ObjectOptionConfig<TCoerce, TProps, TAdditionalProps>
+  ): CLI<
+    TArgs & {
+      [key in TOption]: WithOptional<
+        unknown extends TCoerce
+          ? ResolveProperties<TProps> & AdditionalPropertiesType<TAdditionalProps>
+          : TCoerce,
+        ObjectOptionConfig<TCoerce, TProps, TAdditionalProps>
+      >;
+    }
+  >;
+  // String option overload
+  option<
+    TOption extends string,
+    const TConfig extends StringOptionConfig<any, any>
+  >(
+    name: TOption,
+    config: TConfig
+  ): CLI<
+    TArgs & {
+      [key in TOption]: OptionConfigToType<TConfig>;
+    }
+  >;
+  // Number option overload
+  option<
+    TOption extends string,
+    const TConfig extends NumberOptionConfig<any, any>
+  >(
+    name: TOption,
+    config: TConfig
+  ): CLI<
+    TArgs & {
+      [key in TOption]: OptionConfigToType<TConfig>;
+    }
+  >;
+  // Boolean option overload
+  option<
+    TOption extends string,
+    const TConfig extends BooleanOptionConfig<any, any>
+  >(
+    name: TOption,
+    config: TConfig
+  ): CLI<
+    TArgs & {
+      [key in TOption]: OptionConfigToType<TConfig>;
+    }
+  >;
+  // Array option overload
+  option<
+    TOption extends string,
+    const TConfig extends ArrayOptionConfig<any, any>
+  >(
+    name: TOption,
+    config: TConfig
+  ): CLI<
+    TArgs & {
+      [key in TOption]: OptionConfigToType<TConfig>;
+    }
+  >;
+  // Generic fallback overload
+  option<
+    TOption extends string,
+    const TOptionConfig extends OptionConfig<any, any, any, any>
+  >(
+    name: TOption,
+    config: TOptionConfig
+  ): CLI<
+    TArgs & {
+      [key in TOption]: OptionConfigToType<TOptionConfig>;
+    }
+  >;
+
+  /**
+   * Registers a new positional argument for the CLI command. This argument will be accessible
+   * within the command handler, as well as any subcommands.
+   * @param name The name of the positional argument.
+   * @param config Configuration for the positional argument. See {@link UnknownOptionConfig}.
+   * @returns Updated CLI instance with the new positional argument registered.
+   */
+  // Object option overload - must come first for proper contextual typing
+  // Uses direct ObjectOptionConfig type (not `extends`) to ensure TypeScript
+  // infers TProps from `properties` BEFORE evaluating the coerce callback type
+  positional<
+    TOption extends string,
+    TCoerce,
+    const TProps extends Record<string, { type: string }>,
+    TAdditionalProps extends false | 'string' | 'number' | 'boolean' = false
+  >(
+    name: TOption,
+    config: ObjectOptionConfig<TCoerce, TProps, TAdditionalProps>
+  ): CLI<
+    TArgs & {
+      [key in TOption]: WithOptional<
+        unknown extends TCoerce
+          ? ResolveProperties<TProps> & AdditionalPropertiesType<TAdditionalProps>
+          : TCoerce,
+        ObjectOptionConfig<TCoerce, TProps, TAdditionalProps>
+      >;
+    }
+  >;
+  // String option overload
+  positional<
+    TOption extends string,
+    const TConfig extends StringOptionConfig<any, any>
+  >(
+    name: TOption,
+    config: TConfig
+  ): CLI<
+    TArgs & {
+      [key in TOption]: OptionConfigToType<TConfig>;
+    }
+  >;
+  // Number option overload
+  positional<
+    TOption extends string,
+    const TConfig extends NumberOptionConfig<any, any>
+  >(
+    name: TOption,
+    config: TConfig
+  ): CLI<
+    TArgs & {
+      [key in TOption]: OptionConfigToType<TConfig>;
+    }
+  >;
+  // Boolean option overload
+  positional<
+    TOption extends string,
+    const TConfig extends BooleanOptionConfig<any, any>
+  >(
+    name: TOption,
+    config: TConfig
+  ): CLI<
+    TArgs & {
+      [key in TOption]: OptionConfigToType<TConfig>;
+    }
+  >;
+  // Array option overload
+  positional<
+    TOption extends string,
+    const TConfig extends ArrayOptionConfig<any, any>
+  >(
+    name: TOption,
+    config: TConfig
+  ): CLI<
+    TArgs & {
+      [key in TOption]: OptionConfigToType<TConfig>;
+    }
+  >;
+  // Generic fallback overload
+  positional<
+    TOption extends string,
+    const TOptionConfig extends OptionConfig<any, any, any, any>
+  >(
+    name: TOption,
+    config: TOptionConfig
+  ): CLI<
+    TArgs & {
+      [key in TOption]: OptionConfigToType<TOptionConfig>;
+    }
+  >;
+
+  /**
+   * Adds support for reading CLI options from environment variables.
+   * @param prefix The prefix to use when looking up environment variables. Defaults to the command name.
+   */
+  env(prefix?: string): CLI<TArgs>;
+
+  env(options: EnvOptionConfig): CLI<TArgs>;
+
+  /**
+   * Sets a group of options as mutually exclusive. If more than one option is provided, there will be a validation error.
+   * @param options The options that should be mutually exclusive.
+   */
+  conflicts(...options: [string, string, ...string[]]): CLI<TArgs>;
+
+  /**
+   * Sets a group of options as mutually inclusive. If one option is provided, all other options must also be provided.
+   * @param option The option that implies the other options.
+   * @param impliedOptions The options which become required when the option is provided.
+   */
+  implies(option: string, ...impliedOptions: string[]): CLI<TArgs>;
+
+  /**
+   * Requires a command to be provided when executing the CLI. Useful if your parent command
+   * cannot be executed on its own.
+   * @returns Updated CLI instance.
+   */
+  demandCommand(): CLI<TArgs>;
+
+  /**
+   * Sets the usage text for the CLI. This text will be displayed in place of the default usage text
+   * @param usageText Text displayed in place of the default usage text for `--help` and in generated docs.
+   */
+  usage(usageText: string): CLI<TArgs>;
+
+  /**
+   * Sets the description for the CLI. This text will be displayed in the help text and generated docs.
+   * @param examples Examples to display in the help text and generated docs.
+   */
+  examples(...examples: string[]): CLI<TArgs>;
+
+  /**
+   * Allows overriding the version displayed when passing `--version`. Defaults to crawling
+   * the file system to get the package.json of the currently executing command.
+   * @param override
+   */
+  version(override?: string): CLI<TArgs>;
+
+  /**
+   * Prints help text to stdout.
+   */
+  printHelp(): void;
+
+  group({
+    label,
+    keys,
+    sortOrder,
+  }: {
+    label: string;
+    keys: (keyof TArgs)[];
+    sortOrder: number;
+  }): CLI<TArgs>;
+  group(label: string, keys: (keyof TArgs)[]): CLI<TArgs>;
+
+  middleware<TArgs2>(
+    callback: MiddlewareFunction<TArgs, TArgs2>
+  ): CLI<TArgs2 extends void ? TArgs : TArgs & TArgs2>;
+
+  /**
+   * Parses argv and executes the CLI
+   * @param args argv. Defaults to process.argv.slice(2)
+   * @returns Promise that resolves when the handler completes.
+   */
+  forge(args?: string[]): Promise<TArgs>;
+}
+
+export interface CLIHandlerContext {
+  command: CLI<any>;
+}
+
+/**
+ * Represents the configuration needed to create a CLI command.
+ */
+export interface CLICommandOptions<
+  /**
+   * The type of the arguments that are already registered before `builder` is invoked.
+   */
+  TInitial extends ParsedArgs,
+  /**
+   * The type of the arguments that are registered after `builder` is invoked, and the type that is passed to the handler.
+   */
+  TArgs extends TInitial = TInitial
+> {
+  /**
+   * If set the command will be registered under the provided name and any aliases.
+   *
+   * This can be useful if a command should be executed under more than one name, e.g. `npx my-cli` and `npx my-cli hello`.
+   */
+  alias?: string[];
+
+  /**
+   * The command description. This will be displayed in the help text and generated docs.
+   */
+  description?: string;
+
+  /**
+   * The command builder. This function is called before the command is executed, and is used to register options and positional parameters.
+   * @param parser The parser instance to register options and positionals with.
+   */
+  builder?: (parser: CLI<TInitial>) => CLI<TArgs>;
+
+  /**
+   * The command handler. This function is called when the command is executed.
+   * @param args The parsed arguments.
+   * @param context Context for the handler. Contains the command instance.
+   */
+  handler?: (args: TArgs, context: CLIHandlerContext) => void | Promise<void>;
+
+  /**
+   * The usage text for the command. This text will be displayed in place of the default usage text in the help text and generated docs.
+   */
+  usage?: string;
+
+  /**
+   * Examples to display in the help text and generated docs.
+   */
+  examples?: string[];
+
+  /**
+   * Hides the command from the help text and generated docs. Useful primarily for experimental or internal commands.
+   */
+  hidden?: boolean;
+
+  /**
+   * The epilogue text for the command. This text will be displayed at the end of the help text and generated docs.
+   */
+  epilogue?: string;
+}
+
+export type Command<
+  TInitial extends ParsedArgs = any,
+  TArgs extends TInitial = TInitial
+> =
+  | ({
+      name: string;
+    } & CLICommandOptions<TInitial, TArgs>)
+  | CLI<TArgs>;
+
+/**
+ * Error Handler for CLI applications. Error handlers should re-throw the error if they cannot handle it.
+ *
+ * @param e The error that was thrown.
+ * @param actions Actions that can be taken by the error handler. Prefer using these over process.exit for better support of interactive shells.
+ */
+export type ErrorHandler = (
+  e: unknown,
+  actions: {
+    /**
+     * Exits the process immediately.
+     * @param code
+     */
+    exit: (code?: number) => void;
+  }
+) => void;
+
+export type MiddlewareFunction<TArgs extends ParsedArgs, TArgs2> = (
+  args: TArgs
+) => TArgs2 | Promise<TArgs2>;
+
+/**
+ * Constructs a CLI instance. See {@link CLI} for more information.
+ * @param name Name for the top level CLI
+ * @param rootCommandConfiguration Configuration used when running the bare CLI. e.g. npx my-cli, rather than npx my-cli [cmd]
+ * @returns A {@link CLI} instance.
+ */
+export function cli<TArgs extends ParsedArgs>(
+  name: string,
+  rootCommandConfiguration?: CLICommandOptions<ParsedArgs, TArgs>
+) {
+  return new InternalCLI(name, rootCommandConfiguration) as any as CLI<TArgs>;
+}
+
+export default cli;

package/src/lib/test-harness.spec.ts

@@ -0,0 +1,29 @@
+import cli from './public-api';
+import { TestHarness } from './test-harness';
+
+describe('test harness', () => {
+  it('should not actually run commands', async () => {
+    let commandsExecuted = 0;
+    const cliUnderTest = cli('test').commands(
+      {
+        name: 'foo',
+        builder: (argv) => argv.option('bar', { type: 'string' }),
+        handler: () => {
+          commandsExecuted++;
+        },
+      },
+      {
+        name: 'bar',
+        builder: (argv) => argv.option('baz', { type: 'string' }),
+        handler: () => {
+          commandsExecuted++;
+        },
+      }
+    );
+    const harness = new TestHarness(cliUnderTest);
+    const { commandChain, args } = await harness.parse(['foo', '--bar', 'baz']);
+    expect(commandChain).toEqual(['foo']);
+    expect(commandsExecuted).toEqual(0);
+    expect(args).toEqual({ bar: 'baz', unmatched: [] });
+  });
+});

package/src/lib/test-harness.ts

@@ -0,0 +1,69 @@
+import { ParsedArgs } from '@cli-forge/parser';
+import { InternalCLI } from './internal-cli';
+import { CLI } from './public-api';
+
+export type TestHarnessParseResult<T extends ParsedArgs> = {
+  /**
+   * Parsed arguments. Note the the typing of this is based on the CLI typings,
+   * but no runtime validation outside of the configured validation checks on
+   * individual options will be performed. If you want to validate the arguments,
+   * you should do so in your test or configure a `validate` callback for the option.
+   */
+  args: T;
+
+  /**
+   * The command chain that was resolved during parsing. This is used for testing
+   * that the correct command is ran when resolving a subcommand. A test that checks
+   * this may look like:
+   *
+   * ```ts
+   * const harness = new TestHarness(cli);
+   * const { args, commandChain } = await harness.parse(['hello', '--name=sir']);
+   * expect(commandChain).toEqual(['hello']);
+   * ```
+   *
+   * The above test would check that the `hello` command was resolved when parsing
+   * the argstring, and since only one command's handler will ever be called, this
+   * can be used to ensure that the correct command is ran.
+   */
+  commandChain: string[];
+};
+
+/**
+ * Utility for testing CLI instances. Can check argument parsing and validation, including
+ * command chain resolution.
+ */
+export class TestHarness<T extends ParsedArgs> {
+  private cli: InternalCLI<T>;
+
+  constructor(cli: CLI<T>) {
+    if (cli instanceof InternalCLI) {
+      this.cli = cli;
+      mockHandler(cli);
+    } else {
+      throw new Error(
+        'TestHarness can only be used with CLI instances created by `cli`.'
+      );
+    }
+  }
+
+  async parse(args: string[]): Promise<TestHarnessParseResult<T>> {
+    const argv = await this.cli.forge(args);
+
+    return {
+      args: argv,
+      commandChain: this.cli.commandChain,
+    };
+  }
+}
+
+function mockHandler(cli: InternalCLI) {
+  if (cli.configuration?.handler) {
+    cli.configuration.handler = () => {
+      // Mocked, should do nothing.
+    };
+  }
+  for (const command in cli.registeredCommands) {
+    mockHandler(cli.registeredCommands[command]);
+  }
+}

package/src/lib/utils.spec.ts

@@ -0,0 +1,25 @@
+import { stringToArgs } from './utils';
+
+describe('utils', () => {
+  describe('stringToArgs', () => {
+    it.each([
+      ['hello', ['hello']],
+      ['hello world', ['hello', 'world']],
+      ['hello "world"', ['hello', 'world']],
+      ['hello "mom and dad"', ['hello', 'mom and dad']],
+      [
+        'hello "mom and dad" "brother and sister"',
+        ['hello', 'mom and dad', 'brother and sister'],
+      ],
+      [
+        'hello "mom and \\"dad\\"" "brother and sister"',
+        ['hello', 'mom and "dad"', 'brother and sister'],
+      ],
+      ["hello 'world'", ['hello', 'world']],
+      ["hello 'mom and dad'", ['hello', 'mom and dad']],
+      ['hello \'mom and "dad"\'', ['hello', 'mom and "dad"']],
+    ])(`should parse %s`, (input, expected) => {
+      expect(stringToArgs(input)).toEqual(expected);
+    });
+  });
+});