cli-forge 0.3.0 → 0.5.0

package/bin/cli.d.ts

@@ -1,3 +1,6 @@
 #!/usr/bin/env node
-declare const mycli: import("../src").CLI<import("dist/packages/parser/src").ParsedArgs, import("dist/packages/parser/src").ParsedArgs>;
+declare const mycli: import("../src").CLI<{
+    unmatched: string[];
+    '--'?: string[];
+}>;
 export default mycli;

package/bin/cli.js

@@ -4,7 +4,11 @@ Object.defineProperty(exports, "__esModule", { value: true });
 const src_1 = require("../src");
 const generate_documentation_1 = require("./commands/generate-documentation");
 const init_1 = require("./commands/init");
-const mycli = (0, init_1.withInit)((0, generate_documentation_1.withGenerateDocumentation)((0, src_1.cli)('cli-forge')));
+const mycli = (0, src_1.cli)('cli-forge').commands(generate_documentation_1.generateDocumentationCommand, init_1.initCommand);
 exports.default = mycli;
-mycli.forge();
+if (require.main === module) {
+    (async () => {
+        await mycli.forge();
+    })();
+}
 //# sourceMappingURL=cli.js.map

package/bin/cli.js.map

@@ -1 +1 @@
-{"version":3,"file":"cli.js","sourceRoot":"","sources":["../../../../packages/cli-forge/bin/cli.ts"],"names":[],"mappings":";;;AAEA,gCAA6B;AAC7B,8EAA8E;AAC9E,0CAA2C;AAE3C,MAAM,KAAK,GAAG,IAAA,eAAQ,EAAC,IAAA,kDAAyB,EAAC,IAAA,SAAG,EAAC,WAAW,CAAC,CAAC,CAAC,CAAC;AAEpE,kBAAe,KAAK,CAAC;AAErB,KAAK,CAAC,KAAK,EAAE,CAAC"}
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../../../../packages/cli-forge/bin/cli.ts"],"names":[],"mappings":";;;AAEA,gCAA6B;AAC7B,8EAAiF;AACjF,0CAA8C;AAE9C,MAAM,KAAK,GAAG,IAAA,SAAG,EAAC,WAAW,CAAC,CAAC,QAAQ,CACrC,qDAA4B,EAC5B,kBAAW,CACZ,CAAC;AAEF,kBAAe,KAAK,CAAC;AAErB,IAAI,OAAO,CAAC,IAAI,KAAK,MAAM,EAAE,CAAC;IAC5B,CAAC,KAAK,IAAI,EAAE;QACV,MAAM,KAAK,CAAC,KAAK,EAAE,CAAC;IACtB,CAAC,CAAC,EAAE,CAAC;AACP,CAAC"}

package/bin/commands/generate-documentation.d.ts

@@ -1,20 +1,6 @@
 import type { ParsedArgs } from '@cli-forge/parser';
-import { CLI } from '../../src';
-type GenerateDocsArgs = {
-    cli: string;
-    output: string;
-    format: string;
-    export: string;
-};
-export declare function withGenerateDocumentationArgs<T extends ParsedArgs>(cmd: CLI<T, T & GenerateDocsArgs>): CLI<T & {
-    cli: string;
-} & {
-    output: string;
-} & {
-    format: string;
-} & {
-    export: string;
-}, T & {
+import { CLI } from '../../src/lib/cli-forge';
+export declare function withGenerateDocumentationArgs<T extends ParsedArgs>(cmd: CLI<T>): CLI<T & {
     cli: string;
 } & {
     output: string;
@@ -23,5 +9,4 @@ export declare function withGenerateDocumentationArgs<T extends ParsedArgs>(cmd:
 } & {
     export: string;
 }>;
-export declare function withGenerateDocumentation<T extends ParsedArgs>(cli: CLI<T>): CLI<T, T>;
-export {};
+export declare const generateDocumentationCommand: CLI;

package/bin/commands/generate-documentation.js

@@ -1,11 +1,13 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.generateDocumentationCommand = void 0;
 exports.withGenerateDocumentationArgs = withGenerateDocumentationArgs;
-exports.withGenerateDocumentation = withGenerateDocumentation;
 const node_fs_1 = require("node:fs");
 const node_path_1 = require("node:path");
+const posix_1 = require("node:path/posix");
 const src_1 = require("../../src");
 const documentation_1 = require("../../src/lib/documentation");
+const cli_forge_1 = require("../../src/lib/cli-forge");
 const fs_1 = require("../utils/fs");
 function withGenerateDocumentationArgs(cmd) {
     return cmd
@@ -22,63 +24,65 @@ function withGenerateDocumentationArgs(cmd) {
     })
         .option('format', {
         type: 'string',
-        description: 'What format should the documentation be output in? (json, md)',
+        description: 'What format should the documentation be output in?',
         default: 'md',
+        choices: ['json', 'md'],
     })
         .option('export', {
         type: 'string',
         description: 'The name of the export that contains the CLI instance. By default, docs will be generated for the default export.',
     });
 }
-function withGenerateDocumentation(cli) {
-    return cli.command('generate-documentation', {
-        description: 'Generate documentation for the given CLI',
-        builder: withGenerateDocumentationArgs,
-        handler: async (args) => {
-            if (args.cli.startsWith('./')) {
-                args.cli = (0, node_path_1.join)(process.cwd(), args.cli);
-            }
-            const cliModule = await Promise.resolve(`${args.cli}`).then(s => require(s));
-            const cli = cliModule[args.export || 'default'] ?? cliModule;
-            if (!(cli instanceof src_1.CLI)) {
-                throw new Error(`${args.cli}${args.export ? '#' + args.export : ''} is not a CLI.`);
-            }
-            const documentation = (0, documentation_1.generateDocumentation)(cli);
-            if (args.format === 'md') {
-                await generateMarkdownDocumentation(documentation, args);
-            }
-            else if (args.format === 'json') {
-                const outfile = args.output.endsWith('json')
-                    ? args.output
-                    : (0, node_path_1.join)(args.output, cli.name + '.json');
-                const outdir = (0, node_path_1.dirname)(outfile);
-                (0, fs_1.ensureDirSync)(outdir);
-                (0, node_fs_1.writeFileSync)(outfile, JSON.stringify(documentation, null, 2));
-            }
-        },
-    });
-}
+exports.generateDocumentationCommand = (0, src_1.default)('generate-documentation', {
+    description: 'Generate documentation for the given CLI',
+    builder: (b) => withGenerateDocumentationArgs(b),
+    handler: async (args) => {
+        if (args.cli.startsWith('./') || args.cli.startsWith('../')) {
+            args.cli = (0, node_path_1.join)(process.cwd(), args.cli);
+        }
+        const cliModule = await Promise.resolve(`${args.cli}`).then(s => require(s));
+        const cli = cliModule[args.export || 'default'] ?? cliModule;
+        if (!isCLI(cli)) {
+            throw new Error(`${args.cli}${args.export ? '#' + args.export : ''} is not a CLI.`);
+        }
+        const documentation = (0, documentation_1.generateDocumentation)(cli);
+        if (args.format === 'md') {
+            await generateMarkdownDocumentation(documentation, args);
+        }
+        else if (args.format === 'json') {
+            const outfile = args.output.endsWith('json')
+                ? args.output
+                : (0, node_path_1.join)(args.output, cli.name + '.json');
+            const outdir = (0, node_path_1.dirname)(outfile);
+            (0, fs_1.ensureDirSync)(outdir);
+            (0, node_fs_1.writeFileSync)(outfile, JSON.stringify(documentation, null, 2));
+        }
+    },
+});
 async function generateMarkdownDocumentation(docs, args) {
     const md = await importMarkdownFactory();
-    await generateMarkdownForSingleCommand(docs, (0, node_path_1.join)(args.output, docs.name), md);
+    await generateMarkdownForSingleCommand(docs, args.output, args.output, md);
 }
-async function generateMarkdownForSingleCommand(docs, out, md) {
+async function generateMarkdownForSingleCommand(docs, out, docsRoot, md) {
     const subcommands = docs.subcommands;
     const outdir = subcommands.length ? out : (0, node_path_1.dirname)(out);
     const outname = subcommands.length ? 'index' : docs.name;
     (0, fs_1.ensureDirSync)(outdir);
     (0, node_fs_1.writeFileSync)((0, node_path_1.join)(outdir, outname + '.md'), md.h1(docs.name, ...[
+        [md.bold('Usage:'), md.code(docs.usage)].join(' '),
         docs.description,
         getPositionalArgsFragment(docs.positionals, md),
         getFlagArgsFragment(docs.options, md),
-        getSubcommandsFragment(docs.subcommands, md),
+        getSubcommandsFragment(docs.subcommands, outdir, docsRoot, md),
+        getExamplesFragment(docs.examples, md),
     ].filter(isTruthy)));
     for (const subcommand of docs.subcommands) {
-        await generateMarkdownForSingleCommand(subcommand, (0, node_path_1.join)(outdir, subcommand.name), md);
+        await generateMarkdownForSingleCommand(subcommand, (0, node_path_1.join)(outdir, subcommand.name), docsRoot, md);
     }
 }
 function formatOption(option, md) {
-    return md.h3(option.key, ...[
+    return md.h3(option.deprecated ? md.strikethrough(option.key) : option.key, ...[
+        option.deprecated ? md.bold(md.italics('Deprecated')) : undefined,
         md.bold('Type:') +
             ' ' +
             (option.type === 'array'
@@ -86,7 +90,18 @@ function formatOption(option, md) {
                 : option.type),
         option.description,
         option.default ? md.bold('Default:') + ' ' + option.default : undefined,
-        option.required ? md.bold('Required') : undefined,
+        // No need to show required if it's required and has a default, as its not actually required to pass.
+        option.required && !option.default ? md.bold('Required') : undefined,
+        option.choices
+            ? md.bold('Valid values:') +
+                ' ' +
+                (() => {
+                    const choicesAsString = (typeof option.choices === 'function'
+                        ? option.choices()
+                        : option.choices).map((t) => t.toString());
+                    return choicesAsString.join(', ');
+                })()
+            : undefined,
         option.alias?.length
             ? md.h4('Aliases', md.ul(...option.alias))
             : undefined,
@@ -104,11 +119,12 @@ function getFlagArgsFragment(options, md) {
     }
     return md.h2('Flags', ...Object.values(options).map((option) => formatOption(option, md)));
 }
-function getSubcommandsFragment(subcommands, md) {
+function getSubcommandsFragment(subcommands, outdir, docsRoot, md) {
     if (subcommands.length === 0) {
         return undefined;
     }
-    return md.h2('Subcommands', ...subcommands.map((subcommand) => md.link(`./${subcommand.name}`, subcommand.name)));
+    return md.h2('Subcommands', ...subcommands.map((subcommand) => md.link('./' +
+        (0, posix_1.join)((0, posix_1.normalize)((0, node_path_1.relative)(docsRoot, outdir)), subcommand.name + '.md'), subcommand.name)));
 }
 function isTruthy(value) {
     return !!value;
@@ -121,4 +137,25 @@ async function importMarkdownFactory() {
         throw new Error('Could not find markdown-factory. Please install it to generate markdown documentation.');
     }
 }
+function isCLI(obj) {
+    if (obj instanceof cli_forge_1.InternalCLI) {
+        return true;
+    }
+    if (typeof obj !== 'object' || !obj) {
+        return false;
+    }
+    if (!('constructor' in obj)) {
+        return false;
+    }
+    if (!('name' in obj.constructor)) {
+        return false;
+    }
+    return obj.constructor.name === cli_forge_1.InternalCLI.name;
+}
+function getExamplesFragment(examples, md) {
+    if (examples.length === 0) {
+        return undefined;
+    }
+    return md.h2('Examples', ...examples.map((example) => md.codeBlock(example, 'shell')));
+}
 //# sourceMappingURL=generate-documentation.js.map

package/bin/commands/generate-documentation.js.map

@@ -1 +1 @@
-{"version":3,"file":"generate-documentation.js","sourceRoot":"","sources":["../../../../../packages/cli-forge/bin/commands/generate-documentation.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"generate-documentation.js","sourceRoot":"","sources":["../../../../../packages/cli-forge/bin/commands/generate-documentation.ts"],"names":[],"mappings":"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"}

package/bin/commands/init.d.ts

@@ -1,22 +1,19 @@
 import type { ParsedArgs } from '@cli-forge/parser';
 import { CLI } from '../../src';
-type InitArgs = {
-    cliName: string;
-    output: string;
-    format: string;
-};
-export declare function withInitArgs<T extends ParsedArgs>(cmd: CLI<T, T & InitArgs>): CLI<T & {
+export declare function withInitArgs<T extends ParsedArgs>(cmd: CLI<T>): CLI<T & {
     cliName: string;
 } & {
     output: string;
 } & {
     format: string;
-}, T & {
+}>;
+export declare const initCommand: CLI<{
+    unmatched: string[];
+    '--'?: string[];
+} & {
     cliName: string;
 } & {
     output: string;
 } & {
     format: string;
 }>;
-export declare function withInit<T extends ParsedArgs>(cli: CLI<T>): CLI<T, T>;
-export {};

package/bin/commands/init.js

@@ -1,12 +1,14 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.initCommand = void 0;
 exports.withInitArgs = withInitArgs;
-exports.withInit = withInit;
+const node_child_process_1 = require("node:child_process");
 const node_fs_1 = require("node:fs");
 const node_path_1 = require("node:path");
-const fs_1 = require("../utils/fs");
 const package_json_1 = require("../../package.json");
-const node_child_process_1 = require("node:child_process");
+const src_1 = require("../../src");
+// import { CLI } from '../../src/lib/cli-forge';
+const fs_1 = require("../utils/fs");
 function withInitArgs(cmd) {
     return cmd
         .positional('cliName', {
@@ -22,39 +24,38 @@ function withInitArgs(cmd) {
         .option('format', {
         type: 'string',
         default: 'ts',
-        description: 'What format should the CLI be in? (js, ts)',
-    });
-}
-function withInit(cli) {
-    return cli.command('init', {
-        description: 'Generate a new CLI',
-        builder: withInitArgs,
-        handler: async (args) => {
-            args.output ??= process.cwd();
-            (0, fs_1.ensureDirSync)(args.output);
-            const packageJsonPath = (0, node_path_1.join)(args.output, 'package.json');
-            const cliPath = (0, node_path_1.join)(args.output, 'bin', `${args.cliName}.${args.format}`);
-            const packageJsonContent = readJsonOr(packageJsonPath, { name: args.cliName });
-            packageJsonContent.bin ??= {};
-            packageJsonContent.bin[args.cliName] = (0, node_path_1.relative)(args.output, cliPath);
-            packageJsonContent.dependencies ??= {};
-            packageJsonContent.dependencies['cli-forge'] ??= package_json_1.version;
-            (0, node_fs_1.writeFileSync)(packageJsonPath, JSON.stringify(packageJsonContent, null, 2));
-            (0, fs_1.ensureDirSync)((0, node_path_1.dirname)(cliPath));
-            (0, node_fs_1.writeFileSync)(cliPath, args.format === 'ts'
-                ? TS_CLI_CONTENTS(args.cliName)
-                : JS_CLI_CONTENTS(args.cliName));
-            const installCommand = (0, node_fs_1.existsSync)((0, node_path_1.join)(args.output, 'yarn.lock'))
-                ? 'yarn'
-                : (0, node_fs_1.existsSync)((0, node_path_1.join)(args.output, 'pnpm-lock.yaml'))
-                    ? 'pnpm'
-                    : (0, node_fs_1.existsSync)((0, node_path_1.join)(args.output, 'bun.lockb'))
-                        ? 'bun'
-                        : 'npm';
-            (0, node_child_process_1.execSync)(`${installCommand} install`);
-        },
+        description: 'What format should the CLI be in?',
+        choices: ['js', 'ts'],
     });
 }
+exports.initCommand = (0, src_1.default)('init', {
+    description: 'Generate a new CLI',
+    builder: (b) => withInitArgs(b),
+    handler: async (args) => {
+        args.output ??= process.cwd();
+        (0, fs_1.ensureDirSync)(args.output);
+        const packageJsonPath = (0, node_path_1.join)(args.output, 'package.json');
+        const cliPath = (0, node_path_1.join)(args.output, 'bin', `${args.cliName}.${args.format}`);
+        const packageJsonContent = readJsonOr(packageJsonPath, { name: args.cliName });
+        packageJsonContent.bin ??= {};
+        packageJsonContent.bin[args.cliName] = (0, node_path_1.relative)(args.output, cliPath);
+        packageJsonContent.dependencies ??= {};
+        packageJsonContent.dependencies['cli-forge'] ??= package_json_1.version;
+        (0, node_fs_1.writeFileSync)(packageJsonPath, JSON.stringify(packageJsonContent, null, 2));
+        (0, fs_1.ensureDirSync)((0, node_path_1.dirname)(cliPath));
+        (0, node_fs_1.writeFileSync)(cliPath, args.format === 'ts'
+            ? TS_CLI_CONTENTS(args.cliName)
+            : JS_CLI_CONTENTS(args.cliName));
+        const installCommand = (0, node_fs_1.existsSync)((0, node_path_1.join)(args.output, 'yarn.lock'))
+            ? 'yarn'
+            : (0, node_fs_1.existsSync)((0, node_path_1.join)(args.output, 'pnpm-lock.yaml'))
+                ? 'pnpm'
+                : (0, node_fs_1.existsSync)((0, node_path_1.join)(args.output, 'bun.lockb'))
+                    ? 'bun'
+                    : 'npm';
+        (0, node_child_process_1.execSync)(`${installCommand} install`);
+    },
+});
 const COMMON_CONTENTS = (name) => `const myCLI = cli('${name}')
   .command('hello', {
     builder: (args) => args.positional('name', {type: 'string'}),

package/bin/commands/init.js.map

@@ -1 +1 @@
-{"version":3,"file":"init.js","sourceRoot":"","sources":["../../../../../packages/cli-forge/bin/commands/init.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"init.js","sourceRoot":"","sources":["../../../../../packages/cli-forge/bin/commands/init.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "cli-forge",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "dependencies": {
     "tslib": "^2.3.0",
-    "@cli-forge/parser": "0.3.0"
+    "@cli-forge/parser": "0.5.0"
   },
   "peerDependencies": {
     "markdown-factory": "0.2.0"

package/src/index.d.ts

@@ -1,2 +1,2 @@
-export * from './lib/cli-forge';
-export { default } from './lib/cli-forge';
+export { default, cli, CLI, Command } from './lib/cli-forge';
+export { TestHarness } from './lib/test-harness';

package/src/index.js

@@ -1,8 +1,9 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.default = void 0;
-const tslib_1 = require("tslib");
-tslib_1.__exportStar(require("./lib/cli-forge"), exports);
+exports.TestHarness = exports.cli = exports.default = void 0;
 var cli_forge_1 = require("./lib/cli-forge");
 Object.defineProperty(exports, "default", { enumerable: true, get: function () { return cli_forge_1.default; } });
+Object.defineProperty(exports, "cli", { enumerable: true, get: function () { return cli_forge_1.cli; } });
+var test_harness_1 = require("./lib/test-harness");
+Object.defineProperty(exports, "TestHarness", { enumerable: true, get: function () { return test_harness_1.TestHarness; } });
 //# sourceMappingURL=index.js.map

package/src/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../packages/cli-forge/src/index.ts"],"names":[],"mappings":";;;;AAAA,0DAAgC;AAChC,6CAA0C;AAAjC,oGAAA,OAAO,OAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../packages/cli-forge/src/index.ts"],"names":[],"mappings":";;;AAAA,6CAA6D;AAApD,oGAAA,OAAO,OAAA;AAAE,gGAAA,GAAG,OAAA;AACrB,mDAAiD;AAAxC,2GAAA,WAAW,OAAA"}

package/src/lib/cli-forge.d.ts

@@ -1,16 +1,19 @@
 import { ArrayOptionConfig, OptionConfig, ParsedArgs } from '@cli-forge/parser';
-export type CLICommandOptions<TInitial extends ParsedArgs, TArgs extends TInitial> = {
+export interface CLIHandlerContext {
+    command: CLI<any>;
+}
+export type CLICommandOptions<TInitial extends ParsedArgs, TArgs extends TInitial = TInitial> = {
     description?: string;
     builder?: (parser: CLI<TInitial>) => CLI<TArgs>;
-    handler: (args: TArgs) => void | Promise<void>;
+    handler?: (args: TArgs, context: CLIHandlerContext) => void | Promise<void>;
+    usage?: string;
+    examples?: string[];
 };
-export type ArgsOf<T extends CLI> = T extends {
-    configuration: {
-        handler: (args: infer TArgs) => void;
-    };
-} ? TArgs : never;
+export type Command<TInitial extends ParsedArgs = any, TArgs extends TInitial = TInitial> = ({
+    name: string;
+} & CLICommandOptions<TInitial, TArgs>) | CLI<TArgs>;
 /**
- * The base class for a CLI application. This class is used to define the structure of the CLI.
+ * The interface for a CLI application or subcommands.
  *
  * {@link cli} is provided as a small helper function to create a new CLI instance.
  *
@@ -28,25 +31,25 @@ export type ArgsOf<T extends CLI> = T extends {
  *   }).forge();
  * ```
  */
-export declare class CLI<T extends ParsedArgs = ParsedArgs, T2 extends T = T> {
-    name: string;
-    configuration?: CLICommandOptions<T, T2> | undefined;
-    private commands;
-    private commandChain;
-    private requiresCommand;
-    private parser;
-    /**
-     * @param name What should the name of the cli command be?
-     * @param configuration Configuration for the current CLI command.
-     */
-    constructor(name: string, configuration?: CLICommandOptions<T, T2> | undefined);
+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<TArgs extends T>(key: string, options: CLICommandOptions<T, TArgs>): this;
+    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>;
     /**
      * Registers a new option for the CLI command. This option will be accessible
      * within the command handler, as well as any subcommands.
@@ -55,12 +58,14 @@ export declare class CLI<T extends ParsedArgs = ParsedArgs, T2 extends T = T> {
      * @param config Configuration for the option. See {@link OptionConfig}.
      * @returns Updated CLI instance with the new option registered.
      */
-    option<TOption extends string, TOptionConfig extends OptionConfig>(name: TOption, config: TOptionConfig): CLI<T & { [key in TOption]: TOptionConfig["coerce"] extends (value: string) => infer TCoerce ? TCoerce : {
-        string: string;
-        number: number;
-        boolean: boolean;
-        array: (TOptionConfig extends ArrayOptionConfig<string | number> ? TOptionConfig["items"] extends "string" ? string : number : never)[];
-    }[TOptionConfig["type"]]; }>;
+    option<TOption extends string, TOptionConfig extends OptionConfig>(name: TOption, config: TOptionConfig): CLI<TArgs & {
+        [key in TOption]: TOptionConfig['coerce'] extends (value: string) => infer TCoerce ? TCoerce : {
+            string: string;
+            number: number;
+            boolean: boolean;
+            array: (TOptionConfig extends ArrayOptionConfig<string | number> ? TOptionConfig['items'] extends 'string' ? string : number : never)[];
+        }[TOptionConfig['type']];
+    }>;
     /**
      * Registers a new positional argument for the CLI command. This argument will be accessible
      * within the command handler, as well as any subcommands.
@@ -68,18 +73,109 @@ export declare class CLI<T extends ParsedArgs = ParsedArgs, T2 extends T = T> {
      * @param config Configuration for the positional argument. See {@link OptionConfig}.
      * @returns Updated CLI instance with the new positional argument registered.
      */
-    positional<TOption extends string, TOptionConfig extends OptionConfig>(name: TOption, config: TOptionConfig): CLI<T & { [key in TOption]: TOptionConfig["coerce"] extends (value: string) => infer TCoerce ? TCoerce : {
-        string: string;
-        number: number;
-        boolean: boolean;
-        array: (TOptionConfig extends ArrayOptionConfig<string | number> ? TOptionConfig["items"] extends "string" ? string : number : never)[];
-    }[TOptionConfig["type"]]; }>;
+    positional<TOption extends string, TOptionConfig extends OptionConfig>(name: TOption, config: TOptionConfig): CLI<TArgs & {
+        [key in TOption]: TOptionConfig['coerce'] extends (value: string) => infer TCoerce ? TCoerce : {
+            string: string;
+            number: number;
+            boolean: boolean;
+            array: (TOptionConfig extends ArrayOptionConfig<string | number> ? TOptionConfig['items'] extends 'string' ? string : number : never)[];
+        }[TOptionConfig['type']];
+    }>;
+    /**
+     * 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>;
+    /**
+     * 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>;
+    /**
+     * Prints help text to stdout.
+     */
+    printHelp(): void;
+    /**
+     * 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>;
+}
+/**
+ * The base class for a CLI application. This class is used to define the structure of the CLI.
+ *
+ * {@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 declare class InternalCLI<TArgs extends ParsedArgs = ParsedArgs> implements CLI<TArgs> {
+    name: string;
+    /**
+     * For internal use only. Stick to properties available on {@link CLI}.
+     */
+    registeredCommands: Record<string, InternalCLI<any>>;
+    /**
+     * For internal use only. Stick to properties available on {@link CLI}.
+     */
+    commandChain: string[];
+    private requiresCommand;
+    private _configuration?;
+    get configuration(): CLICommandOptions<any, any> | undefined;
+    private set configuration(value);
+    private parser;
+    /**
+     * @param name What should the name of the cli command be?
+     * @param configuration Configuration for the current CLI command.
+     */
+    constructor(name: string);
+    withRootCommandConfiguration<TRootCommandArgs extends TArgs>(configuration: CLICommandOptions<TArgs, TRootCommandArgs>): InternalCLI<TArgs>;
+    command<TCommandArgs extends TArgs>(cmd: Command<TArgs, TCommandArgs>): CLI<TArgs>;
+    command<TCommandArgs extends TArgs>(key: string, options: CLICommandOptions<TArgs, TCommandArgs>): CLI<TArgs>;
+    commands(commands: Command[]): CLI<TArgs>;
+    commands(...commands: Command[]): CLI<TArgs>;
+    option<TOption extends string, TOptionConfig extends OptionConfig>(name: TOption, config: TOptionConfig): any;
+    positional<TOption extends string, TOptionConfig extends OptionConfig>(name: TOption, config: TOptionConfig): any;
+    conflicts(...args: [string, string, ...string[]]): CLI<TArgs>;
+    implies(option: string, ...impliedOptions: string[]): CLI<TArgs>;
+    env(prefix?: string): this;
     demandCommand(): this;
+    usage(usageText: string): this;
+    examples(...examples: string[]): this;
     /**
      * Gets help text for the current command as a string.
      * @returns Help text for the current command.
@@ -94,23 +190,24 @@ export declare class CLI<T extends ParsedArgs = ParsedArgs, T2 extends T = T> {
      * @param cmd The command to run.
      * @param args The arguments to pass to the command.
      */
-    runCommand<T extends ParsedArgs>(cmd: CLI<T>, args: T): Promise<void>;
+    runCommand<T extends ParsedArgs>(cmd: InternalCLI<T>, args: T): Promise<void>;
     /**
      * 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<void>;
-    getParser(): import("@cli-forge/parser").ReadonlyArgvParser<T & {
+    forge(args?: string[]): Promise<TArgs>;
+    getParser(): import("@cli-forge/parser").ReadonlyArgvParser<TArgs & {
         help: boolean;
     }>;
-    getSubcommands(): Readonly<Record<string, CLI>>;
-    clone(): CLI<T, T2>;
+    getSubcommands(): Readonly<Record<string, InternalCLI>>;
+    clone(): InternalCLI<TArgs>;
 }
 /**
- * Constructs a CLI instance. See {@link CLI} for more information.
+ * Constructs a CLI instance. See {@link InternalCLI} for more information.
  * @param name Name for the top level CLI
- * @returns
+ * @param rootCommandConfiguration Configuration used when running the bare CLI. e.g. npx my-cli, rather than npx my-cli [cmd]
+ * @returns A {@link InternalCLI} instance.
  */
-export declare function cli(name: string): CLI<ParsedArgs, ParsedArgs>;
+export declare function cli<TArgs extends ParsedArgs>(name: string, rootCommandConfiguration?: CLICommandOptions<ParsedArgs, TArgs>): CLI<TArgs>;
 export default cli;

package/src/lib/cli-forge.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.CLI = void 0;
+exports.InternalCLI = void 0;
 exports.cli = cli;
 const parser_1 = require("@cli-forge/parser");
 /**
@@ -22,20 +22,32 @@ const parser_1 = require("@cli-forge/parser");
  *   }).forge();
  * ```
  */
-class CLI {
+class InternalCLI {
     name;
-    configuration;
-    commands = {};
+    /**
+     * For internal use only. Stick to properties available on {@link CLI}.
+     */
+    registeredCommands = {};
+    /**
+     * For internal use only. Stick to properties available on {@link CLI}.
+     */
     commandChain = [];
     requiresCommand = false;
+    _configuration;
+    get configuration() {
+        return this._configuration;
+    }
+    set configuration(value) {
+        this._configuration = value;
+    }
     parser = new parser_1.ArgvParser({
         unmatchedParser: (arg) => {
             // eslint-disable-next-line @typescript-eslint/no-this-alias
             let currentCommand = this;
             for (const command of this.commandChain) {
-                currentCommand = currentCommand.commands[command];
+                currentCommand = currentCommand.registeredCommands[command];
             }
-            const command = currentCommand.commands[arg];
+            const command = currentCommand.registeredCommands[arg];
             if (command && command.configuration) {
                 command.configuration.builder?.(command);
                 this.commandChain.push(arg);
@@ -52,61 +64,95 @@ class CLI {
      * @param name What should the name of the cli command be?
      * @param configuration Configuration for the current CLI command.
      */
-    constructor(name, configuration) {
+    constructor(name) {
         this.name = name;
+    }
+    withRootCommandConfiguration(configuration) {
         this.configuration = configuration;
+        this.requiresCommand = false;
+        return this;
     }
-    /**
-     * 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(key, options) {
-        if (key === '$0') {
-            this.configuration = {
-                ...this.configuration,
-                builder: options.builder,
-                handler: options.handler,
-                description: options.description,
-            };
-        }
-        this.commands[key] = new CLI(key, options);
-        this.commands[key].parser = this.parser;
+    command(keyOrCommand, options) {
+        if (typeof keyOrCommand === 'string') {
+            const key = keyOrCommand;
+            if (!options) {
+                throw new Error('options must be provided when calling `command` with a string');
+            }
+            if (key === '$0') {
+                this.configuration = {
+                    ...this.configuration,
+                    builder: options.builder,
+                    handler: options.handler,
+                    description: options.description,
+                };
+                this.requiresCommand = false;
+            }
+            this.registeredCommands[key] = new InternalCLI(key).withRootCommandConfiguration(options);
+            this.registeredCommands[key].parser = this.parser;
+        }
+        else if (keyOrCommand instanceof InternalCLI) {
+            const cmd = keyOrCommand;
+            this.registeredCommands[cmd.name] = cmd;
+        }
+        else {
+            const { name, ...configuration } = keyOrCommand;
+            this.command(name, configuration);
+        }
+        return this;
+    }
+    commands(...a0) {
+        const commands = a0.flat();
+        for (const val of commands) {
+            if (val instanceof InternalCLI) {
+                this.registeredCommands[val.name] = val;
+                // Include any options that were defined via cli(...).option() instead of via builder
+                this.parser.augment(val.parser);
+                val.parser = this.parser;
+            }
+            else {
+                const { name, ...configuration } = val;
+                this.command(name, configuration);
+            }
+        }
         return this;
     }
-    /**
-     * 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 OptionConfig}.
-     * @returns Updated CLI instance with the new option registered.
-     */
     option(name, config) {
         this.parser.option(name, config);
+        // Interface modifies the return type to reflect new params, cast is necessay.... I think 🤔
         return this;
     }
-    /**
-     * 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 OptionConfig}.
-     * @returns Updated CLI instance with the new positional argument registered.
-     */
     positional(name, config) {
         this.parser.positional(name, config);
+        // Interface modifies the return type to reflect new params, cast is necessay.... I think 🤔
+        return this;
+    }
+    conflicts(...args) {
+        this.parser.conflicts(...args);
+        return this;
+    }
+    implies(option, ...impliedOptions) {
+        this.parser.implies(option, ...impliedOptions);
+        return this;
+    }
+    env(prefix = (0, parser_1.fromCamelOrDashedCaseToConstCase)(this.name)) {
+        this.parser.env(prefix);
         return this;
     }
-    /**
-     * 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() {
         this.requiresCommand = true;
         return this;
     }
+    usage(usageText) {
+        this.configuration ??= {};
+        this.configuration.usage = usageText;
+        return this;
+    }
+    examples(...examples) {
+        this.configuration ??= {};
+        this.configuration.examples ??= [];
+        this.configuration.examples.push(...examples);
+        return this;
+    }
     /**
      * Gets help text for the current command as a string.
      * @returns Help text for the current command.
@@ -116,22 +162,24 @@ class CLI {
         // eslint-disable-next-line @typescript-eslint/no-this-alias
         let command = this;
         for (const key of this.commandChain) {
-            command = command.commands[key];
+            command = command.registeredCommands[key];
         }
-        help.push(`Usage: ${[
-            this.name,
-            ...this.commandChain,
-            ...command.parser.configuredPositionals.map((p) => `[${p.key}]`),
-        ].join(' ')}`);
+        help.push(`Usage: ${this.configuration?.usage
+            ? this.configuration.usage
+            : [
+                this.name,
+                ...this.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.commands).length > 0) {
+        if (Object.keys(command.registeredCommands).length > 0) {
             help.push('');
             help.push('Commands:');
         }
-        for (const key in command.commands) {
-            const subcommand = command.commands[key];
+        for (const key in command.registeredCommands) {
+            const subcommand = command.registeredCommands[key];
             help.push(`  ${key}${subcommand.configuration?.description
                 ? ' - ' + subcommand.configuration.description
                 : ''}`);
@@ -140,11 +188,55 @@ class CLI {
             help.push('');
             help.push('Options:');
         }
+        function getOptionParts(key, option) {
+            const parts = [];
+            if (option.description) {
+                parts.push(option.description);
+            }
+            if (option.choices) {
+                const choices = typeof option.choices === 'function'
+                    ? option.choices()
+                    : option.choices;
+                parts.push(`(${choices.join(', ')})`);
+            }
+            if (option.default) {
+                parts.push('[default: ' + option.default + ']');
+            }
+            else if (option.required) {
+                parts.push('[required]');
+            }
+            if (option.deprecated) {
+                parts.push('[deprecated: ' + option.deprecated + ']');
+            }
+            return parts;
+        }
+        const allParts = [];
         for (const key in this.parser.configuredOptions) {
             const option = this.parser.configuredOptions[key];
-            help.push(`  --${key}${option.description ? ' - ' + option.description : ''}`);
+            allParts.push([key, ...getOptionParts(key, option)]);
+        }
+        const paddingValues = [];
+        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) {
+            help.push(`  --${key.padEnd(paddingValues[0])}${parts.length ? ' - ' : ''}${parts
+                .map((part, i) => part.padEnd(paddingValues[i + 1]))
+                .join(' ')}`);
         }
-        if (Object.keys(command.commands).length > 0) {
+        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 \`${[this.name, ...this.commandChain].join(' ')} [command] --help\` for more information on a command`);
         }
@@ -167,7 +259,9 @@ class CLI {
                 throw new Error(`${[this.name, ...this.commandChain].join(' ')} requires a command`);
             }
             if (cmd.configuration?.handler) {
-                await cmd.configuration.handler(args);
+                await cmd.configuration.handler(args, {
+                    command: cmd,
+                });
             }
             else {
                 throw new Error(`${[this.name, ...this.commandChain].join(' ')} is not implemented.`);
@@ -184,48 +278,78 @@ class CLI {
      * @param args argv. Defaults to process.argv.slice(2)
      * @returns Promise that resolves when the handler completes.
      */
-    async forge(args = process.argv.slice(2)) {
+    async forge(args = (0, parser_1.hideBin)(process.argv)) {
         // Parsing the args does two things:
         // - builds argv to pass to handler
         // - fills the command chain + registers commands
-        const argv = this.parser.parse(args);
+        let argv;
+        let validationFailedError;
+        try {
+            argv = this.parser.parse(args);
+        }
+        catch (e) {
+            if (e instanceof parser_1.ValidationFailedError) {
+                argv = e.partialArgV;
+                validationFailedError = e;
+            }
+            else {
+                throw e;
+            }
+        }
         // eslint-disable-next-line @typescript-eslint/no-this-alias
         let currentCommand = this;
         for (const command of this.commandChain) {
-            currentCommand = currentCommand.commands[command];
+            currentCommand = currentCommand.registeredCommands[command];
         }
         if (argv.help) {
             this.printHelp();
-            return;
+            return argv;
+        }
+        else if (validationFailedError) {
+            this.printHelp();
+            throw validationFailedError;
         }
         const finalArgV = currentCommand === this
-            ? (this.configuration?.builder?.(this).parser ?? this.parser).parse(args)
+            ? (this.configuration?.builder?.(this)
+                ?.parser ?? this.parser).parse(args)
             : argv;
         await this.runCommand(currentCommand, finalArgV);
+        return finalArgV;
     }
     getParser() {
         return this.parser.asReadonly();
     }
     getSubcommands() {
-        return this.commands;
+        return this.registeredCommands;
     }
     clone() {
-        const clone = new CLI(this.name, this.configuration);
-        clone.commands = { ...this.commands };
+        const clone = new InternalCLI(this.name);
+        if (this.configuration) {
+            clone.withRootCommandConfiguration(this.configuration);
+        }
+        clone.registeredCommands = { ...this.registeredCommands };
         clone.commandChain = [...this.commandChain];
         clone.requiresCommand = this.requiresCommand;
         clone.parser = this.parser.clone();
         return clone;
     }
 }
-exports.CLI = CLI;
+exports.InternalCLI = InternalCLI;
 /**
- * Constructs a CLI instance. See {@link CLI} for more information.
+ * Constructs a CLI instance. See {@link InternalCLI} for more information.
  * @param name Name for the top level CLI
- * @returns
+ * @param rootCommandConfiguration Configuration used when running the bare CLI. e.g. npx my-cli, rather than npx my-cli [cmd]
+ * @returns A {@link InternalCLI} instance.
  */
-function cli(name) {
-    return new CLI(name);
+function cli(name, rootCommandConfiguration) {
+    const cli = new InternalCLI(name);
+    if (rootCommandConfiguration) {
+        cli.withRootCommandConfiguration(rootCommandConfiguration);
+    }
+    else {
+        cli.demandCommand();
+    }
+    return cli;
 }
 exports.default = cli;
 //# sourceMappingURL=cli-forge.js.map

package/src/lib/cli-forge.js.map

@@ -1 +1 @@
-{"version":3,"file":"cli-forge.js","sourceRoot":"","sources":["../../../../../packages/cli-forge/src/lib/cli-forge.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"cli-forge.js","sourceRoot":"","sources":["../../../../../packages/cli-forge/src/lib/cli-forge.ts"],"names":[],"mappings":"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"}

package/src/lib/documentation.d.ts

@@ -1,8 +1,10 @@
 import { OptionConfig } from '@cli-forge/parser';
-import { CLI } from './cli-forge';
+import { InternalCLI } from './cli-forge';
 export type Documentation = {
     name: string;
     description?: string;
+    usage: string;
+    examples: string[];
     options: Readonly<Record<string, OptionConfig & {
         key: string;
     }>>;
@@ -11,9 +13,11 @@ export type Documentation = {
     }>[];
     subcommands: Documentation[];
 };
-export declare function generateDocumentation(cli: CLI): {
+export declare function generateDocumentation(cli: InternalCLI, commandChain?: string[]): {
     name: string;
     description: string | undefined;
+    usage: string;
+    examples: string[];
     options: Readonly<{
         unmatched: OptionConfig<any> & {
             key: string;

package/src/lib/documentation.js

@@ -1,7 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.generateDocumentation = generateDocumentation;
-function generateDocumentation(cli) {
+function generateDocumentation(cli, commandChain = []) {
     // Ensure current command's options are built.
     if (cli.configuration?.builder) {
         cli.configuration.builder(cli);
@@ -9,10 +9,20 @@ function generateDocumentation(cli) {
     const parser = cli.getParser();
     const options = parser.configuredOptions;
     const positionals = parser.configuredPositionals;
-    const subcommands = Object.values(cli.getSubcommands()).map((cmd) => generateDocumentation(cmd.clone()));
+    const subcommands = 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(' '),
+        examples: cli.configuration?.examples ?? [],
         options,
         positionals,
         subcommands,

package/src/lib/documentation.js.map

@@ -1 +1 @@
-{"version":3,"file":"documentation.js","sourceRoot":"","sources":["../../../../../packages/cli-forge/src/lib/documentation.ts"],"names":[],"mappings":";;AAWA,sDAoBC;AApBD,SAAgB,qBAAqB,CAAC,GAAQ;IAC5C,8CAA8C;IAC9C,IAAI,GAAG,CAAC,aAAa,EAAE,OAAO,EAAE,CAAC;QAC/B,GAAG,CAAC,aAAa,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;IACjC,CAAC;IACD,MAAM,MAAM,GAAG,GAAG,CAAC,SAAS,EAAE,CAAC;IAE/B,MAAM,OAAO,GAAG,MAAM,CAAC,iBAAiB,CAAC;IACzC,MAAM,WAAW,GAAG,MAAM,CAAC,qBAAqB,CAAC;IACjD,MAAM,WAAW,GAAoB,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC,cAAc,EAAE,CAAC,CAAC,GAAG,CAC1E,CAAC,GAAG,EAAE,EAAE,CAAC,qBAAqB,CAAC,GAAG,CAAC,KAAK,EAAE,CAAC,CAC5C,CAAC;IAEF,OAAO;QACL,IAAI,EAAE,GAAG,CAAC,IAAI;QACd,WAAW,EAAE,GAAG,CAAC,aAAa,EAAE,WAAW;QAC3C,OAAO;QACP,WAAW;QACX,WAAW;KACZ,CAAC;AACJ,CAAC"}
+{"version":3,"file":"documentation.js","sourceRoot":"","sources":["../../../../../packages/cli-forge/src/lib/documentation.ts"],"names":[],"mappings":";;AAaA,sDAiCC;AAjCD,SAAgB,qBAAqB,CACnC,GAAgB,EAChB,eAAyB,EAAE;IAE3B,8CAA8C;IAC9C,IAAI,GAAG,CAAC,aAAa,EAAE,OAAO,EAAE,CAAC;QAC/B,GAAG,CAAC,aAAa,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;IACjC,CAAC;IACD,MAAM,MAAM,GAAG,GAAG,CAAC,SAAS,EAAE,CAAC;IAE/B,MAAM,OAAO,GAAG,MAAM,CAAC,iBAAiB,CAAC;IACzC,MAAM,WAAW,GAAG,MAAM,CAAC,qBAAqB,CAAC;IACjD,MAAM,WAAW,GAAoB,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC,cAAc,EAAE,CAAC,CAAC,GAAG,CAC1E,CAAC,GAAG,EAAE,EAAE,CAAC,qBAAqB,CAAC,GAAG,CAAC,KAAK,EAAE,EAAE,CAAC,GAAG,YAAY,EAAE,GAAG,CAAC,IAAI,CAAC,CAAC,CACzE,CAAC;IAEF,OAAO;QACL,IAAI,EAAE,GAAG,CAAC,IAAI;QACd,WAAW,EAAE,GAAG,CAAC,aAAa,EAAE,WAAW;QAC3C,KAAK,EAAE,GAAG,CAAC,aAAa,EAAE,KAAK;YAC7B,CAAC,CAAC,YAAY,CAAC,MAAM;gBACnB,CAAC,CAAC,CAAC,GAAG,YAAY,EAAE,GAAG,CAAC,aAAa,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC;gBACtD,CAAC,CAAC,GAAG,CAAC,aAAa,EAAE,KAAK;YAC5B,CAAC,CAAC;gBACE,GAAG,YAAY;gBACf,GAAG,CAAC,IAAI;gBACR,GAAG,WAAW,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,GAAG,GAAG,CAAC,CAAC;aACtE,CAAC,IAAI,CAAC,GAAG,CAAC;QACf,QAAQ,EAAE,GAAG,CAAC,aAAa,EAAE,QAAQ,IAAI,EAAE;QAC3C,OAAO;QACP,WAAW;QACX,WAAW;KACZ,CAAC;AACJ,CAAC"}

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

@@ -0,0 +1,36 @@
+import { ParsedArgs } from '@cli-forge/parser';
+import { CLI } from './cli-forge';
+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 declare class TestHarness<T extends ParsedArgs> {
+    private cli;
+    constructor(cli: CLI<T>);
+    parse(args: string[]): Promise<TestHarnessParseResult<T>>;
+}

package/src/lib/test-harness.js

@@ -0,0 +1,37 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TestHarness = void 0;
+const cli_forge_1 = require("./cli-forge");
+/**
+ * Utility for testing CLI instances. Can check argument parsing and validation, including
+ * command chain resolution.
+ */
+class TestHarness {
+    cli;
+    constructor(cli) {
+        if (cli instanceof cli_forge_1.InternalCLI) {
+            this.cli = cli;
+            mockHandler(cli);
+        }
+        else {
+            throw new Error('TestHarness can only be used with CLI instances created by `cli`.');
+        }
+    }
+    async parse(args) {
+        const argv = await this.cli.forge(args);
+        return {
+            args: argv,
+            commandChain: this.cli.commandChain,
+        };
+    }
+}
+exports.TestHarness = TestHarness;
+function mockHandler(cli) {
+    if (cli.configuration?.handler) {
+        cli.configuration.handler = () => { };
+    }
+    for (const command in cli.registeredCommands) {
+        mockHandler(cli.registeredCommands[command]);
+    }
+}
+//# sourceMappingURL=test-harness.js.map

package/src/lib/test-harness.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"test-harness.js","sourceRoot":"","sources":["../../../../../packages/cli-forge/src/lib/test-harness.ts"],"names":[],"mappings":";;;AACA,2CAA+C;AA6B/C;;;GAGG;AACH,MAAa,WAAW;IACd,GAAG,CAAiB;IAE5B,YAAY,GAAW;QACrB,IAAI,GAAG,YAAY,uBAAW,EAAE,CAAC;YAC/B,IAAI,CAAC,GAAG,GAAG,GAAG,CAAC;YACf,WAAW,CAAC,GAAG,CAAC,CAAC;QACnB,CAAC;aAAM,CAAC;YACN,MAAM,IAAI,KAAK,CACb,mEAAmE,CACpE,CAAC;QACJ,CAAC;IACH,CAAC;IAED,KAAK,CAAC,KAAK,CAAC,IAAc;QACxB,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QAExC,OAAO;YACL,IAAI,EAAE,IAAI;YACV,YAAY,EAAE,IAAI,CAAC,GAAG,CAAC,YAAY;SACpC,CAAC;IACJ,CAAC;CACF;AAtBD,kCAsBC;AAED,SAAS,WAAW,CAAC,GAAgB;IACnC,IAAI,GAAG,CAAC,aAAa,EAAE,OAAO,EAAE,CAAC;QAC/B,GAAG,CAAC,aAAa,CAAC,OAAO,GAAG,GAAG,EAAE,GAAE,CAAC,CAAC;IACvC,CAAC;IACD,KAAK,MAAM,OAAO,IAAI,GAAG,CAAC,kBAAkB,EAAE,CAAC;QAC7C,WAAW,CAAC,GAAG,CAAC,kBAAkB,CAAC,OAAO,CAAC,CAAC,CAAC;IAC/C,CAAC;AACH,CAAC"}