cli-forge 0.10.1 → 0.12.0

package/src/bin/commands/init.ts

@@ -0,0 +1,320 @@
+import type { ParsedArgs } from '@cli-forge/parser';
+
+import { execSync } from 'node:child_process';
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join, relative } from 'node:path';
+
+import cli, { CLI } from '../..';
+
+import { ensureDirSync } from '../utils/fs';
+
+const CLI_FORGE_PACKAGE_JSON = (() => {
+  let path = __dirname;
+  while (!existsSync(join(path, 'package.json'))) {
+    path = dirname(path);
+  }
+  return JSON.parse(readFileSync(join(path, 'package.json'), 'utf-8'));
+})();
+
+const CLI_FORGE_VERSION = CLI_FORGE_PACKAGE_JSON.version;
+
+/**
+ * These are peer dependencies that **we** will call require/import on,
+ * but are not actually required at runtime. These are mostly optional,
+ * and used when running `cli-forge` commands rather than the user's CLI.
+ */
+const DEV_PEER_DEPS = Object.entries(
+  CLI_FORGE_PACKAGE_JSON.peerDependencies
+).reduce((acc, [dep, version]) => {
+  // The dev prop doesn't actually do anything for npm/pnpm/yarn,
+  // but we are using it to mark when a peer dep is only used at dev time.
+  // In these cases, we can safely add them to the devDependencies of the
+  // generated CLI.
+  const meta =
+    CLI_FORGE_PACKAGE_JSON.peerDependenciesMeta[
+      dep as keyof typeof CLI_FORGE_PACKAGE_JSON.peerDependenciesMeta
+    ];
+  if (meta && 'dev' in meta && meta.dev) {
+    acc[dep] = version as string;
+  }
+  return acc;
+}, {} as Record<string, string>);
+
+export function withInitArgs<T extends ParsedArgs>(cmd: CLI<T>) {
+  return cmd
+    .positional('cliName', {
+      type: 'string',
+      description: 'Name of the CLI to generate.',
+      required: true,
+    })
+    .option('output', {
+      alias: ['o'],
+      type: 'string',
+      description: 'Where should the CLI be created?',
+    })
+    .option('format', {
+      type: 'string',
+      default: 'ts',
+      description: 'What format should the CLI be in?',
+      choices: ['js', 'ts'],
+    })
+    .option('initialVersion', {
+      type: 'string',
+      default: '0.0.1',
+      description:
+        'Initial version used when creating the package.json for the new CLI.',
+    });
+}
+
+export const initCommand = cli('init', {
+  description: 'Generate a new CLI',
+  builder: (b) => withInitArgs(b),
+  handler: async (args) => {
+    args.output ??= join(process.cwd(), args.cliName);
+    ensureDirSync(args.output);
+    const packageJsonPath = join(args.output, 'package.json');
+    const cliPathWithoutExtension = join(args.output, 'bin', `${args.cliName}`);
+    const cliPath = [cliPathWithoutExtension, args.format].join('.');
+
+    let packageJsonContent: PackageJson = readJsonOr(packageJsonPath, {
+      name: args.cliName,
+      version: args.initialVersion,
+    });
+    packageJsonContent = mergePackageJsonContents(packageJsonContent, {
+      name: args.cliName,
+      version: args.initialVersion,
+      bin: {
+        [args.cliName]: relative(args.output, cliPathWithoutExtension),
+      },
+      dependencies: {
+        'cli-forge': CLI_FORGE_VERSION,
+      },
+    });
+    if (args.format === 'ts') {
+      const latestTypescriptVersion = execSync('npm show typescript version')
+        .toString()
+        .trim();
+      const latestTsConfigNodeVersion = execSync(
+        'npm show @tsconfig/node-lts version'
+      )
+        .toString()
+        .trim();
+      packageJsonContent = mergePackageJsonContents(packageJsonContent, {
+        scripts: {
+          build: 'tsx scripts/build.ts',
+        },
+        devDependencies: Object.fromEntries(
+          Object.entries({
+            typescript: latestTypescriptVersion,
+            '@tsconfig/node-lts': latestTsConfigNodeVersion,
+            ...DEV_PEER_DEPS,
+          }).sort(([a], [b]) => a.localeCompare(b))
+        ),
+      });
+      ensureDirSync(join(args.output, 'scripts'));
+      writeFileSync(
+        join(args.output, 'scripts/build.ts'),
+        `import { execSync } from 'node:child_process';
+import { cpSync } from 'node:fs';
+
+execSync('tsc --build tsconfig.json', { stdio: 'inherit' });
+cpSync('package.json', 'dist/package.json');
+        `
+      );
+      writeFileSync(
+        join(args.output, 'tsconfig.json'),
+        JSON.stringify(
+          {
+            extends: '@tsconfig/node-lts',
+            compilerOptions: {
+              rootDir: '.',
+              outDir: 'dist',
+              strict: true,
+            },
+            include: ['src/**/*.ts', 'bin/**/*.ts'],
+            exclude: ['**/*.{spec,test}.ts'],
+          },
+          null,
+          2
+        )
+      );
+    }
+    writeFileSync(
+      packageJsonPath,
+      JSON.stringify(
+        orderKeysInJson(packageJsonContent, [
+          'name',
+          'version',
+          'scripts',
+          'bin',
+          'dependencies',
+          'devDependencies',
+        ]),
+        null,
+        2
+      )
+    );
+    ensureDirSync(dirname(cliPath));
+    writeFileSync(
+      cliPath,
+      args.format === 'ts'
+        ? TS_CLI_CONTENTS(args.cliName)
+        : JS_CLI_CONTENTS(args.cliName)
+    );
+    writeFileSync(
+      join(args.output, 'README.md'),
+      README_CONTENTS(args.cliName, args.format)
+    );
+    const installCommand = existsSync(join(args.output, 'yarn.lock'))
+      ? 'yarn'
+      : existsSync(join(args.output, 'pnpm-lock.yaml'))
+      ? 'pnpm'
+      : existsSync(join(args.output, 'bun.lockb'))
+      ? 'bun'
+      : 'npm';
+
+    execSync(`${installCommand} install`, {
+      cwd: args.output,
+    });
+  },
+});
+
+const COMMON_CONTENTS = (name: string) => `const myCLI = cli('${name}')
+  .command('hello', {
+    builder: (args) => args.positional('name', {type: 'string'}),
+    handler: (args) => {
+      console.log('hello', args.name);
+    }
+  })`;
+
+const README_CONTENTS = (name: string, format: 'js' | 'ts') => `# ${name}
+
+${
+  format === 'ts' ? 'TypeScript' : 'JavaScript'
+} CLI generated by [cli-forge](https://craigory.dev/cli-forge)
+
+## Usage
+
+// Fill this in with usage instructions
+
+## Development
+
+${format === 'ts' ? 'To build the CLI, run `npm run build`' : ''}
+
+To run the CLI, use the following command:
+
+\`\`\`shell
+${
+  format === 'ts' ? 'npm run build && node ./dist/bin' : 'node ./bin'
+}/${name} hello world
+\`\`\`
+
+${
+  format === 'ts'
+    ? `> Hint: you can also use \`npx tsx ./bin/${name} hello world\` to run the CLI without building it first`
+    : ''
+}
+`;
+
+const JS_CLI_CONTENTS = (name: string) => `const { cli } = require('cli-forge');
+
+${COMMON_CONTENTS(name)}
+
+module.exports = myCLI;
+
+if (require.main === module) {
+  myCLI.forge();
+}
+`;
+
+const TS_CLI_CONTENTS = (name: string) => `import { cli } from 'cli-forge';
+
+${COMMON_CONTENTS(name)}
+
+export default myCLI;
+
+if (require.main === module) {
+  myCLI.forge();
+}
+`;
+
+function readJsonOr<T>(filePath: string, alt: T): T {
+  try {
+    const contents = readFileSync(filePath, 'utf-8');
+    return JSON.parse(contents);
+  } catch {
+    return alt;
+  }
+}
+
+type PackageJson = {
+  name: string;
+  version?: string;
+  bin?: {
+    [cmd: string]: string;
+  };
+  scripts?: Record<string, string>;
+  dependencies?: Record<string, string>;
+  devDependencies?: Record<string, string>;
+};
+
+function mergePackageJsonContents(
+  original: PackageJson,
+  updates: Partial<PackageJson>,
+  overwriteExistingValues = false
+): PackageJson {
+  const first = overwriteExistingValues ? original : updates;
+  const second = overwriteExistingValues ? updates : original;
+
+  const merged: PackageJson = {
+    name: original.name ?? updates.name,
+    ...first,
+    ...second,
+  };
+
+  if (first.bin && second.bin) {
+    merged.bin = {
+      ...first.bin,
+      ...second.bin,
+    };
+  }
+
+  if (first.dependencies && second.dependencies) {
+    merged.dependencies = {
+      ...first.dependencies,
+      ...second.dependencies,
+    };
+  }
+
+  if (first.devDependencies && second.devDependencies) {
+    merged.devDependencies = {
+      ...first.devDependencies,
+      ...second.devDependencies,
+    };
+  }
+
+  return merged;
+}
+
+function orderKeysInJson<T extends Record<string, unknown>>(
+  obj: T,
+  order: Array<keyof T & string>
+): T {
+  const values = new Map(Object.entries(obj));
+  const keys = new Set(Object.keys(obj));
+  const returnObj = {} as T;
+
+  for (const key of order) {
+    const value = values.get(key);
+    if (value !== undefined) {
+      returnObj[key] = value as T[typeof key];
+      keys.delete(key);
+    }
+  }
+
+  for (const key of keys) {
+    (returnObj as any)[key] = values.get(key) as T[typeof key];
+  }
+
+  return returnObj;
+}

package/src/bin/utils/fs.ts

@@ -0,0 +1,11 @@
+import { existsSync, mkdirSync } from 'node:fs';
+
+export function ensureDirSync(dir: string) {
+  try {
+    mkdirSync(dir, { recursive: true });
+  } catch (e) {
+    if (!existsSync(dir)) {
+      throw new Error(`Could not create directory: ${dir}`, { cause: e });
+    }
+  }
+}

package/src/index.ts

@@ -0,0 +1,12 @@
+export { TestHarness } from './lib/test-harness';
+export * from './lib/public-api';
+export { default } from './lib/public-api';
+export { chain } from '@cli-forge/parser';
+export { makeComposableBuilder } from './lib/composable-builder';
+export type {
+  ComposableBuilder,
+  ExtractArgs,
+  ExtractChildren,
+} from './lib/composable-builder';
+export type { ArgumentsOf } from './lib/utils';
+export { ConfigurationProviders } from './lib/configuration-providers';

package/src/lib/cli-option-groups.ts

@@ -0,0 +1,69 @@
+import { InternalOptionConfig } from '@cli-forge/parser';
+import { InternalCLI } from './internal-cli';
+
+export function readOptionGroupsForCLI(parentCLI: InternalCLI<any>) {
+  function registerGroupsFromCLI(cli: InternalCLI) {
+    for (const { label, keys, sortOrder } of cli.registeredOptionGroups) {
+      groups[label] ??= {
+        keys: new Set(),
+        sortOrder: Number.MAX_SAFE_INTEGER,
+      };
+      if (sortOrder) {
+        groups[label].sortOrder = sortOrder;
+      }
+      for (const key of keys) {
+        groups[label].keys.add(key);
+      }
+    }
+  }
+
+  const groups: Record<string, { keys: Set<string>; sortOrder: number }> = {};
+  // eslint-disable-next-line @typescript-eslint/no-this-alias
+  let command: InternalCLI<any> = parentCLI;
+  registerGroupsFromCLI(command);
+  for (const subcommand of parentCLI.commandChain) {
+    command = command?.registeredCommands[subcommand];
+    registerGroupsFromCLI(command);
+  }
+  const parserOptions: Record<string, InternalOptionConfig> =
+    parentCLI.parser.configuredOptions;
+
+  for (const key in parserOptions) {
+    const option = parserOptions[key];
+    if (option.group) {
+      groups[option.group] ??= {
+        keys: new Set(),
+        sortOrder: Number.MAX_SAFE_INTEGER,
+      };
+      groups[option.group].keys.add(key);
+    }
+  }
+
+  const groupedOptions: Array<{
+    label: string;
+    sortOrder: number;
+    keys: Array<InternalOptionConfig>;
+  }> = [];
+
+  for (const label in groups) {
+    const entry = {
+      sortOrder: groups[label].sortOrder,
+      keys: [] as InternalOptionConfig[],
+      label,
+    };
+    for (const key of groups[label].keys) {
+      const option = parserOptions[key];
+      entry.keys.push(option);
+      delete parserOptions[key];
+    }
+    groupedOptions.push(entry);
+  }
+  groupedOptions.sort((a, b) => {
+    if (a.sortOrder === b.sortOrder) {
+      return a.label.localeCompare(b.label);
+    } else {
+      return a.sortOrder - b.sortOrder;
+    }
+  });
+  return groupedOptions;
+}

package/src/lib/composable-builder.ts

@@ -0,0 +1,57 @@
+import { ParsedArgs } from '@cli-forge/parser';
+import { CLI } from './public-api';
+
+/**
+ * Extracts the TChildren type parameter from a CLI type.
+ */
+export type ExtractChildren<T> = T extends CLI<any, any, infer C, any>
+  ? C
+  : never;
+
+/**
+ * Extracts the TArgs type parameter from a CLI type.
+ */
+export type ExtractArgs<T> = T extends CLI<infer A, any, any, any> ? A : never;
+
+/**
+ * Type for a composable builder function that transforms a CLI.
+ * Used with `chain` to compose multiple builders.
+ */
+export type ComposableBuilder<
+  TArgs2 extends ParsedArgs,
+  // eslint-disable-next-line @typescript-eslint/ban-types
+  TAddedChildren = {}
+> = <TInit extends ParsedArgs, THandlerReturn, TChildren, TParent>(
+  init: CLI<TInit, THandlerReturn, TChildren, TParent>
+) => CLI<TInit & TArgs2, THandlerReturn, TChildren & TAddedChildren, TParent>;
+
+/**
+ * Creates a composable builder function that can be used with `chain`.
+ * Can be used to add options, commands, or any other CLI modifications.
+ * Children added by the builder function are properly tracked in the type.
+ *
+ * @typeParam TArgs2 - The args type after the builder runs
+ * @typeParam TChildren2 - The children type added by the builder
+ */
+export function makeComposableBuilder<
+  TArgs2 extends ParsedArgs,
+  // eslint-disable-next-line @typescript-eslint/ban-types
+  TChildren2 = {}
+>(
+  fn: (
+    // eslint-disable-next-line @typescript-eslint/ban-types
+    init: CLI<ParsedArgs, any, {}, any>
+  ) => CLI<TArgs2, any, TChildren2, any>
+) {
+  return <TInit extends ParsedArgs, THandlerReturn, TChildren, TParent>(
+    init: CLI<TInit, THandlerReturn, TChildren, TParent>
+  ) =>
+    // eslint-disable-next-line @typescript-eslint/ban-types
+    fn(init as unknown as CLI<ParsedArgs, any, {}, any>) as unknown as CLI<
+      TInit & TArgs2,
+      THandlerReturn,
+      TChildren & TChildren2,
+      TParent
+    >;
+}
+

package/src/lib/configuration-providers.ts

@@ -0,0 +1,36 @@
+import { ConfigurationFiles } from '@cli-forge/parser';
+
+/**
+ * A collection of built-in configuration provider factories. These should be invoked and passed to
+ * {@link CLI.config} to load configuration from various sources. For custom configuration providers, see
+ * https://craigory.dev/cli-forge/api/parser/namespaces/ConfigurationFiles/type-aliases/ConfigurationProvider
+ *
+ * @example
+ * ```typescript
+ * import { cli, ConfigurationProviders } from 'cli-forge';
+ *
+ * cli(...).config(ConfigurationProviders.PackageJson('myConfig'));
+ * ```
+ */
+export const ConfigurationProviders = {
+  /**
+   * Load configuration from a package.json file.
+   *
+   * @param key The key in the package.json file to load as configuration.
+   */
+  PackageJson<T>(key: string) {
+    return ConfigurationFiles.getPackageJsonConfigurationLoader<T>(key);
+  },
+
+  /**
+   * Load configuration from a JSON file.
+   *
+   * @param filename The filename of the JSON file to load.
+   * @param key The key in the JSON file to load as configuration. By default, the entire JSON object is loaded.
+   */
+  JsonFile<T>(filename: string, key?: string) {
+    return ConfigurationFiles.getJsonFileConfigLoader<T>(filename, (json) =>
+      key ? json[key] : json
+    );
+  },
+};

package/src/lib/documentation.spec.ts

@@ -0,0 +1,156 @@
+import { InternalCLI } from './internal-cli';
+import { generateDocumentation } from './documentation';
+import cli from './public-api';
+
+describe('generateDocumentation', () => {
+  it('should not document hidden commands and options', () => {
+    const docs = generateDocumentation(
+      cli('test')
+        .command('foo', {
+          hidden: true,
+          builder: (argv) => argv.option('bar', { type: 'string' }),
+          handler: () => {
+            // not executed.
+          },
+        })
+        .command('bar', {
+          builder: (argv) =>
+            argv
+              .option('a', { type: 'string' })
+              .option('b', { type: 'string', hidden: true }),
+          handler: () => {
+            // not executed.
+          },
+        }) as unknown as InternalCLI
+    );
+    expect(docs.subcommands.find((d) => d.name === 'foo')).toBeUndefined();
+
+    const barDocs = docs.subcommands.find((d) => d.name === 'bar');
+    expect(barDocs).toBeDefined();
+    expect(barDocs?.options?.['a']).toBeDefined();
+    expect(barDocs?.options?.['b']).toBeUndefined();
+  });
+
+  it('should not execute command handlers', () => {
+    let ran = false;
+    generateDocumentation(
+      cli('test').command('foo', {
+        builder: (argv) => argv.option('bar', { type: 'string' }),
+        handler: () => {
+          ran = true;
+        },
+      }) as unknown as InternalCLI
+    );
+    expect(ran).toBe(false);
+  });
+
+  it('should not contain sibling command arguments in current command documentation', () => {
+    const docs = generateDocumentation(
+      cli('test')
+        .command('foo', {
+          builder: (argv) => argv.option('bar', { type: 'string' }),
+          handler: () => {
+            // not executed.
+          },
+        })
+        .command('bar', {
+          builder: (argv) => argv.option('baz', { type: 'string' }),
+          handler: () => {
+            // not executed.
+          },
+        }) as unknown as InternalCLI
+    );
+    const fooDocs = docs.subcommands.find((d) => d.name === 'foo');
+    expect(fooDocs).toBeDefined();
+    // Baz is only registered on the 'bar' command.
+    expect(fooDocs?.options?.['baz']).toBeUndefined();
+    // Bar is only registered on the 'foo' command.
+    expect(fooDocs?.options?.['bar']).toBeDefined();
+
+    const barDocs = docs.subcommands.find((d) => d.name === 'bar');
+    expect(barDocs).toBeDefined();
+    // Bar is only registered on the 'foo' command.
+    expect(barDocs?.options?.['bar']).toBeUndefined();
+    // Baz is only registered on the 'bar' command.
+    expect(barDocs?.options?.['baz']).toBeDefined();
+  });
+
+  it('should group options by group', () => {
+    const docs = generateDocumentation(
+      cli('test')
+        .option('baz', { type: 'string' })
+        .option('bar', { type: 'string' })
+        .option('foo', {
+          type: 'string',
+        })
+        .group('Advanced', ['foo', 'bar']) as unknown as InternalCLI
+    );
+    const advanced = docs.groupedOptions.find((g) => g.label === 'Advanced');
+    expect(advanced).toBeDefined();
+    expect(advanced?.keys.map((k) => k.key)).toEqual(['foo', 'bar']);
+  });
+
+  // TODO: This test should not fail.
+  it.skip('should contain parent command arguments in subcommand documentation', () => {
+    const docs = generateDocumentation(
+      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: () => {
+                // not executed.
+              },
+            }),
+          handler: () => {
+            // not executed.
+          },
+        }) as unknown as InternalCLI
+    );
+    const formatDocs = docs.subcommands.find((d) => d.name === 'format');
+    expect(formatDocs).toBeDefined();
+    expect(formatDocs?.options?.['baz']).toBeDefined();
+    expect(formatDocs?.options?.['bar']).toBeDefined();
+    expect(formatDocs?.options?.['foo']).toBeUndefined();
+
+    const checkDocs = formatDocs?.subcommands.find((d) => d.name === 'check');
+    expect(checkDocs).toBeDefined();
+    expect(checkDocs?.options?.['baz']).toBeDefined();
+    expect(checkDocs?.options?.['bar']).toBeDefined();
+    expect(checkDocs?.options?.['foo']).toBeDefined();
+  });
+
+  it('should document epilogue, which inherits from parent command', () => {
+    const docs = generateDocumentation(
+      cli('test')
+        .command('foo', {
+          epilogue: 'foo epilogue',
+          builder: (argv) =>
+            argv.option('bar', { type: 'string' }).command('subcommand', {}),
+          handler: () => {
+            // not executed.
+          },
+        })
+        .command('bar', {
+          builder: (argv) => argv.option('baz', { type: 'string' }),
+          handler: () => {
+            // not executed.
+          },
+        }) as unknown as InternalCLI
+    );
+    const fooDocs = docs.subcommands.find((d) => d.name === 'foo');
+    expect(fooDocs).toBeDefined();
+    expect(fooDocs?.epilogue).toBe('foo epilogue');
+
+    const subcommandDocs = fooDocs?.subcommands.find(
+      (d) => d.name === 'subcommand'
+    );
+    expect(subcommandDocs).toBeDefined();
+    expect(subcommandDocs?.epilogue).toBe('foo epilogue');
+
+    const barDocs = docs.subcommands.find((d) => d.name === 'bar');
+    expect(barDocs).toBeDefined();
+    expect(barDocs?.epilogue).toBeUndefined();
+  });
+});