cli-forge 0.10.1 → 0.11.0

package/src/lib/documentation.ts

@@ -0,0 +1,107 @@
+import {
+  UnknownOptionConfig,
+  OptionConfigToType,
+  readDefaultValue,
+} from '@cli-forge/parser';
+import { InternalCLI } from './internal-cli';
+import { CLI } from './public-api';
+
+export type Documentation = {
+  name: string;
+  description?: string;
+  epilogue?: string;
+  usage: string;
+  examples: string[];
+  options: Readonly<Record<string, NormalizedOptionConfig>>;
+  positionals: readonly Readonly<NormalizedOptionConfig>[];
+  groupedOptions: Array<{
+    label: string;
+    keys: Array<NormalizedOptionConfig>;
+  }>;
+  subcommands: Documentation[];
+};
+
+function normalizeOptionConfigForDocumentation<T extends UnknownOptionConfig>(
+  option: T,
+  key: string
+) {
+  const { default: declaredDefault, ...rest } = option;
+  let resolvedDefault: OptionConfigToType<T> | string | undefined;
+  if (declaredDefault !== undefined) {
+    const [defaultValue, description] = readDefaultValue(option);
+    resolvedDefault = description ?? defaultValue;
+  }
+  const result: typeof rest & {
+    key: string;
+    default?: OptionConfigToType<T> | string | undefined;
+  } = { ...rest, key };
+  if (resolvedDefault !== undefined) {
+    result.default = resolvedDefault;
+  }
+  return result;
+}
+
+type NormalizedOptionConfig<
+  T extends UnknownOptionConfig = UnknownOptionConfig
+> = ReturnType<typeof normalizeOptionConfigForDocumentation<T>>;
+
+export function generateDocumentation(
+  cli: InternalCLI,
+  commandChain: string[] = []
+) {
+  // Ensure current command's options are built.
+  if (cli.configuration?.builder) {
+    // The cli instance here is typed a bit too well
+    // for the builder function, so we need to cast it to
+    // a more generic form.
+    cli.configuration.builder(cli as CLI);
+  }
+  const parser = cli.getParser();
+
+  const groupedOptions = cli.getGroupedOptions();
+  const options: Record<string, NormalizedOptionConfig> = Object.fromEntries(
+    Object.entries(parser.configuredOptions)
+      .filter(([, c]) => !c.hidden)
+      .map(([k, v]) => [k, normalizeOptionConfigForDocumentation(v, k)])
+  );
+  const positionals = parser.configuredPositionals;
+  for (const positional of positionals) {
+    delete options[positional.key];
+  }
+  const subcommands: Documentation[] = [];
+  for (const subcommand of Object.values(cli.getSubcommands())) {
+    if (subcommand.configuration?.hidden !== true) {
+      const clone = subcommand.clone();
+      if (clone.configuration) {
+        clone.configuration.epilogue ??= cli.configuration?.epilogue;
+      }
+      subcommands.push(
+        generateDocumentation(clone, [...commandChain, cli.name])
+      );
+    }
+  }
+
+  Object.values(cli.getSubcommands()).map((cmd) =>
+    generateDocumentation(cmd.clone(), [...commandChain, cli.name])
+  );
+
+  return {
+    name: cli.name,
+    description: cli.configuration?.description,
+    usage: cli.configuration?.usage
+      ? commandChain.length
+        ? [...commandChain, cli.configuration.usage].join(' ')
+        : cli.configuration?.usage
+      : [
+          ...commandChain,
+          cli.name,
+          ...positionals.map((p) => (p.required ? `<${p.key}>` : `[${p.key}]`)),
+        ].join(' '),
+    epilogue: cli.configuration?.epilogue,
+    examples: cli.configuration?.examples ?? [],
+    groupedOptions,
+    options,
+    positionals,
+    subcommands,
+  } as Documentation;
+}

package/src/lib/format-help.ts

@@ -0,0 +1,149 @@
+import {
+  InternalOptionConfig,
+  UnknownOptionConfig,
+  readDefaultValue,
+} from '@cli-forge/parser';
+import { InternalCLI } from './internal-cli';
+
+export function formatHelp(parentCLI: InternalCLI<any>): string {
+  const help: string[] = [];
+  let command = parentCLI;
+  let epilogue = parentCLI.configuration?.epilogue;
+  for (const key of parentCLI.commandChain) {
+    command = command.registeredCommands[key] as typeof parentCLI;
+
+    // Properties that are ineherited from the parent command should be copied over
+    if (command.configuration?.epilogue) {
+      epilogue = command.configuration.epilogue;
+    }
+  }
+  help.push(
+    `Usage: ${
+      command.configuration?.usage
+        ? command.configuration.usage
+        : [
+            parentCLI.name,
+            ...parentCLI.commandChain,
+            ...command.parser.configuredPositionals.map((p) =>
+              p.required ? `<${p.key}>` : `[${p.key}]`
+            ),
+          ].join(' ')
+    }`
+  );
+  if (command.configuration?.description) {
+    help.push(command.configuration.description);
+  }
+  if (Object.keys(command.registeredCommands).length > 0) {
+    help.push('');
+    help.push('Commands:');
+  }
+  for (const key in command.registeredCommands) {
+    const subcommand = command.registeredCommands[key];
+    help.push(
+      `  ${key}${
+        subcommand.configuration?.description
+          ? ' - ' + subcommand.configuration.description
+          : ''
+      }`
+    );
+  }
+  const groupedOptions = parentCLI.getGroupedOptions();
+  const nonpositionalOptions = Object.values(
+    command.parser.configuredOptions
+  ).filter((c) => !c.positional);
+
+  help.push(...getOptionBlock('Options', nonpositionalOptions));
+
+  for (const { label, keys } of groupedOptions) {
+    help.push(...getOptionBlock(label, keys));
+  }
+
+  if (command.configuration?.examples?.length) {
+    help.push('');
+    help.push('Examples:');
+    for (const example of command.configuration.examples) {
+      help.push(`  \`${example}\``);
+    }
+  }
+
+  if (Object.keys(command.registeredCommands).length > 0) {
+    help.push(' ');
+    help.push(
+      `Run \`${[parentCLI.name, ...parentCLI.commandChain].join(
+        ' '
+      )} [command] --help\` for more information on a command`
+    );
+  }
+
+  if (epilogue) {
+    help.push('');
+    help.push(epilogue);
+  }
+
+  return help.join('\n');
+}
+
+function getOptionParts(option: UnknownOptionConfig) {
+  const parts = [];
+  if (option.description) {
+    parts.push(option.description);
+  }
+  if ('choices' in option && option.choices) {
+    const choices =
+      typeof option.choices === 'function' ? option.choices() : option.choices;
+    parts.push(`(${choices.join(', ')})`);
+  }
+  if (option.default) {
+    parts.push(
+      '[default: ' + formatDefaultValue(readDefaultValue(option)) + ']'
+    );
+  } else if (option.required) {
+    parts.push('[required]');
+  }
+  if (option.deprecated) {
+    parts.push('[deprecated: ' + option.deprecated + ']');
+  }
+  return parts;
+}
+
+function formatDefaultValue([value, description]: [any, string | undefined]) {
+  if (description) {
+    return description;
+  }
+  return removeTrailingAndLeadingQuotes(JSON.stringify(value));
+}
+
+function removeTrailingAndLeadingQuotes(str: string) {
+  return str.replace(/^['"]/, '').replace(/['"]$/, '');
+}
+
+function getOptionBlock(label: string, options: InternalOptionConfig[]) {
+  const lines: string[] = [];
+
+  if (options.length > 0) {
+    lines.push('');
+    lines.push(label + ':');
+  }
+
+  const allParts: Array<[key: string, ...parts: string[]]> = [];
+  for (const option of options) {
+    allParts.push([option.key, ...getOptionParts(option)]);
+  }
+  const paddingValues: number[] = [];
+  for (let i = 0; i < allParts.length; i++) {
+    for (let j = 0; j < allParts[i].length; j++) {
+      if (!paddingValues[j]) {
+        paddingValues[j] = 0;
+      }
+      paddingValues[j] = Math.max(paddingValues[j], allParts[i][j].length);
+    }
+  }
+  for (const [key, ...parts] of allParts) {
+    lines.push(
+      `  --${key.padEnd(paddingValues[0])}${parts.length ? ' - ' : ''}${parts
+        .map((part, i) => part.padEnd(paddingValues[i + 1]))
+        .join(' ')}`
+    );
+  }
+  return lines;
+}

package/src/lib/interactive-shell.ts

@@ -0,0 +1,115 @@
+import * as readline from 'readline';
+import { stringToArgs } from './utils';
+import { InternalCLI } from './internal-cli';
+import { execSync, spawnSync } from 'child_process';
+import { getBin } from '@cli-forge/parser';
+
+export interface InteractiveShellOptions {
+  prompt?: string;
+  prependArgs?: string[];
+}
+
+type NormalizedInteractiveShellOptions = Required<InteractiveShellOptions>;
+
+function normalizeShellOptions(
+  cli: InternalCLI,
+  options?: InteractiveShellOptions
+): NormalizedInteractiveShellOptions {
+  return {
+    prompt:
+      options?.prompt ??
+      (() => {
+        const chain = [cli.name];
+        if (cli.commandChain.length > 2) {
+          chain.push('...', ...cli.commandChain[cli.command.length - 1]);
+        } else {
+          chain.push(...cli.commandChain);
+        }
+        return chain.join(' ') + ' > ';
+      })(),
+    prependArgs: options?.prependArgs ?? [],
+  };
+}
+
+export let INTERACTIVE_SHELL: InteractiveShell | undefined;
+
+export class InteractiveShell {
+  private readonly rl: readline.Interface;
+  private listeners: any[] = [];
+
+  constructor(cli: InternalCLI<any>, opts?: InteractiveShellOptions) {
+    if (INTERACTIVE_SHELL) {
+      throw new Error(
+        'Only one interactive shell can be created at a time. Make sure the other instance is closed.'
+      );
+    }
+    // eslint-disable-next-line @typescript-eslint/no-this-alias
+    INTERACTIVE_SHELL = this;
+
+    const { prompt, prependArgs } = normalizeShellOptions(cli, opts);
+
+    this.rl = readline
+      .createInterface({
+        input: process.stdin,
+        output: process.stdout,
+        prompt: prompt,
+      })
+      .once('SIGINT', () => {
+        process.emit('SIGINT');
+      });
+
+    this.rl.prompt();
+
+    this.registerLineListener(async (line) => {
+      const nextArgs = stringToArgs(line);
+      let currentCommand = cli;
+      for (const subcommand of cli.commandChain) {
+        currentCommand = currentCommand.registeredCommands[subcommand];
+      }
+      if (currentCommand.registeredCommands[nextArgs[0]]) {
+        spawnSync(
+          process.execPath,
+          [
+            ...process.execArgv,
+            getBin(process.argv),
+            ...prependArgs,
+            ...nextArgs,
+          ],
+          { stdio: 'inherit' }
+        );
+      } else if (nextArgs[0] === 'help') {
+        currentCommand.clone().printHelp();
+      } else if (nextArgs[0] === 'exit') {
+        this.close();
+        return true;
+      } else if (line.trim()) {
+        try {
+          execSync(line, { stdio: 'inherit' });
+        } catch {
+          // ignore
+        }
+      }
+      return false;
+    });
+  }
+
+  registerLineListener(callback: (line: string) => Promise<boolean | void>) {
+    const wrapped = async (line: string) => {
+      this.rl.pause();
+      const shouldHalt = await callback(line);
+      if (!shouldHalt) this.rl.prompt();
+    };
+    this.listeners.push(wrapped);
+    this.rl.on('line', wrapped);
+  }
+
+  close() {
+    this.listeners.forEach((listener) => this.rl.off('line', listener));
+    this.rl.close();
+    readline.moveCursor(process.stdout, -1 * this.rl.getCursorPos().cols, 0);
+    readline.clearScreenDown(process.stdout);
+    if (INTERACTIVE_SHELL === this) {
+      INTERACTIVE_SHELL = undefined;
+    }
+  }
+}

package/src/lib/internal-cli.spec.ts

@@ -0,0 +1,345 @@
+import { InternalCLI } from './internal-cli';
+import { cli } from './public-api';
+
+const ORIGINAL_CONSOLE_LOG = console.log;
+
+function mockConsoleLog() {
+  const lines: string[] = [];
+  console.log = (...contents) =>
+    lines.push(
+      contents
+        .map((s) => (typeof s === 'string' ? s : JSON.stringify(s)))
+        .join(' ')
+    );
+  return {
+    getOutput: () => lines.join('\n'),
+    restore: () => {
+      console.log = ORIGINAL_CONSOLE_LOG;
+    },
+  };
+}
+
+describe('cliForge', () => {
+  afterEach(() => {
+    // Tests that contain handlers which fail
+    // set process.exitCode to 1
+    process.exitCode = undefined;
+
+    // Restore console.log
+    console.log = ORIGINAL_CONSOLE_LOG;
+  });
+
+  it('typings should work', async () => {
+    await cli('test cli')
+      .option('foo', { type: 'string', required: true })
+      .command('bar', {
+        builder: (argv) => argv.option('baz', { type: 'number' }),
+        handler: (args) => {
+          // baz should be a number
+          args.baz?.toFixed();
+
+          // foo should be a string
+          args.foo.concat('bar');
+        },
+      })
+      .forge(['--foo', 'hello', 'bar', '--baz', '42']);
+  });
+
+  it('should run commands', async () => {
+    let ran = false;
+    let bar;
+    await cli('test')
+      .command('foo', {
+        builder: (argv) => argv.option('bar', { type: 'string' }),
+        handler: (args) => {
+          ran = true;
+          bar = args.bar;
+        },
+      })
+      .forge(['foo', '--bar', 'baz']);
+    expect(ran).toBe(true);
+    expect(bar).toBe('baz');
+  });
+
+  it('should run commands by alias', async () => {
+    const ran: Record<string, number> = {};
+    const makeHandler = (name: string) => () => {
+      ran[name] = (ran[name] || 0) + 1;
+    };
+
+    const test = cli('test')
+      .command('foo', {
+        alias: ['f'],
+        builder: (argv) => argv,
+        handler: makeHandler('foo'),
+      })
+      .command('bar', {
+        alias: ['$0'],
+        builder: (argv) => argv,
+        handler: makeHandler('bar'),
+      }) as InternalCLI;
+    await test.clone().forge(['f']);
+    await test.clone().forge(['foo']);
+    await test.clone().forge(['bar']);
+    await test.clone().forge([]);
+    expect(ran).toMatchInlineSnapshot(`
+      {
+        "bar": 2,
+        "foo": 2,
+      }
+    `);
+  });
+
+  it('should run parent command if no subcommand is given', () => {
+    const ran = { foo: false, bar: false };
+    cli('test')
+      .command('$0', {
+        builder: (argv) => argv.option('bar', { type: 'string' }),
+        handler: () => {
+          ran.foo = true;
+        },
+      })
+      .command('bar', {
+        builder: (argv) => argv.option('baz', { type: 'string' }),
+        handler: () => {
+          ran.bar = true;
+        },
+      })
+      .forge(['something']);
+    expect(ran.foo).toBe(true);
+  });
+
+  it('should be able to run subcommands', () => {
+    const ran = { format: false, formatCheck: false };
+    cli('test')
+      .option('baz', { type: 'string' })
+      .command('format', {
+        builder: (argv) =>
+          argv.option('bar', { type: 'string' }).command('check', {
+            builder: (argv) => argv.option('foo', { type: 'string' }),
+            handler: (argv) => {
+              // Checks that all parent command options are available on
+              // subcommands.
+              argv.bar;
+              argv.foo;
+              argv.baz;
+              ran.formatCheck = true;
+            },
+          }),
+        handler: () => {
+          ran.format = true;
+        },
+      })
+      .forge(['format', 'check']);
+    expect(ran).toMatchInlineSnapshot(`
+      {
+        "format": false,
+        "formatCheck": true,
+      }
+    `);
+  });
+
+  it('should generate help text', async () => {
+    const { getOutput } = mockConsoleLog();
+    await cli('test')
+      .option('baz', { type: 'string', choices: ['a', 'b'] })
+      .option('qux', {
+        type: 'string',
+        required: true,
+      })
+      .option('quux', {
+        type: 'string',
+        default: 'a',
+      })
+      .command('format', {
+        builder: (argv) =>
+          argv.option('bar', { type: 'string' }).command('check', {
+            builder: (argv) => argv.option('foo', { type: 'string' }),
+            handler: () => {
+              // No side effect needed.
+            },
+          }),
+        handler: () => {
+          // Not invoked.
+        },
+      })
+      .forge(['--help']);
+    expect(getOutput()).toMatchInlineSnapshot(`
+      "Usage: test
+
+      Commands:
+        format
+
+      Options:
+        --help    - Show help for the current command  
+        --version - Show the version number for the CLI
+        --baz     - (a, b)                             
+        --qux     - [required]                         
+        --quux    - [default: a]                       
+       
+      Run \`test [command] --help\` for more information on a command"
+    `);
+  });
+
+  it('should generate help text for subcommands', async () => {
+    const { getOutput } = mockConsoleLog();
+    await cli('test')
+      .option('baz', { type: 'string' })
+      .command('format', {
+        builder: (argv) =>
+          argv.option('bar', { type: 'string' }).command('check', {
+            builder: (argv) => {
+              return argv.option('foo', { type: 'string' });
+            },
+            handler: () => {
+              // No side effect needed.
+            },
+          }),
+        handler: () => {
+          // Not invoked.
+        },
+      })
+      .forge(['format', 'check', '--help']);
+    expect(getOutput()).toMatchInlineSnapshot(`
+      "Usage: test format check
+
+      Options:
+        --help    - Show help for the current command  
+        --version - Show the version number for the CLI
+        --baz    
+        --bar    
+        --foo    "
+    `);
+  });
+
+  it('should print help if command throws', async () => {
+    const { getOutput } = mockConsoleLog();
+    await cli('test')
+      .command('foo', {
+        builder: (argv) => argv.option('bar', { type: 'string' }),
+        handler: () => {
+          throw new Error('test');
+        },
+      })
+      .forge(['foo']);
+    expect(getOutput()).toMatchInlineSnapshot(`
+      "Usage: test foo
+
+      Options:
+        --help    - Show help for the current command  
+        --version - Show the version number for the CLI
+        --bar    "
+    `);
+    expect(process.exitCode).toBe(1);
+  });
+
+  it('should support async handlers', async () => {
+    let ran = false;
+    await cli('test')
+      .command('foo', {
+        builder: (argv) => argv.option('bar', { type: 'string' }),
+        handler: async () => {
+          await new Promise((resolve) => setTimeout(resolve, 1));
+          ran = true;
+        },
+      })
+      .forge(['foo']);
+    expect(ran).toBe(true);
+  });
+
+  it('should support requiring subcommands', async () => {
+    let ran = false;
+    await cli('test')
+      .command('foo', {
+        builder: (argv) => argv.option('bar', { type: 'string' }),
+        handler: () => {
+          ran = true;
+        },
+      })
+      .command('$0', {
+        handler: () => {
+          ran = true;
+        },
+      })
+      .demandCommand()
+      .forge([]);
+
+    // With `demandCommand`, no command should be ran. Instead, the help text should be printed.
+    expect(ran).toBe(false);
+    expect(process.exitCode).toBe(1);
+  });
+
+  it('should support displaying grouped options in help', async () => {
+    const { getOutput } = mockConsoleLog();
+    await cli('test')
+      .option('foo', { type: 'string', group: 'Basic' })
+      .option('baz', { type: 'string' })
+      .option('qux', { type: 'string' })
+      .option('quux', { type: 'string' })
+      .group('Advanced', ['baz', 'qux'])
+      .forge(['--help']);
+
+    expect(getOutput()).toMatchInlineSnapshot(`
+      "Usage: test
+
+      Options:
+        --help    - Show help for the current command  
+        --version - Show the version number for the CLI
+        --quux   
+
+      Advanced:
+        --baz
+        --qux
+
+      Basic:
+        --foo"
+    `);
+  });
+
+  it('should run middlewares before command handlers', async () => {
+    const executionOrder: string[] = [];
+    await cli('test')
+      .middleware((args) => {
+        executionOrder.push('middleware1');
+        return args;
+      })
+      .middleware((args) => {
+        executionOrder.push('middleware2');
+        return args;
+      })
+      .command('foo', {
+        builder: (argv) =>
+          argv.middleware((args) => {
+            executionOrder.push('middleware3');
+            return args;
+          }),
+        handler: () => {
+          executionOrder.push('foo handler');
+        },
+      })
+      .command('bar', {
+        builder: (argv) =>
+          argv.middleware((args) => {
+            executionOrder.push('middleware4');
+            return args;
+          }),
+        handler: () => {
+          executionOrder.push('bar handler');
+        },
+      })
+      .forge(['foo']);
+
+    expect(executionOrder).toEqual([
+      // middlewares first, only for the command being executed
+      'middleware1',
+      'middleware2',
+      'middleware3',
+      // then the handler
+      'foo handler',
+
+      // NO:
+      // - middlewares for the 'bar' command
+      // - 'bar' handler
+    ]);
+  });
+});