cli-nano 1.1.3 → 1.2.0

package/README.md

@@ -9,11 +9,11 @@
 
 ## cli-nano
 
-Simple library to create command-line tool (aka CLI) which is quite similar to [`Yargs`](https://github.com/yargs/yargs), it is as configurable as Yargs but is a fraction of its size. The library is also inspired by NodeJS `parseArgs()` but is again more configurable so that we really get what we would expect from a more complete CLI builder.
+Small library to create command-line tool (aka CLI) which is quite similar to [`Yargs`](https://github.com/yargs/yargs), it is as configurable as Yargs but is a fraction of its size. The library is also inspired by NodeJS `parseArgs()` but is a lot more configurable in order to get what we would expect from a more complete CLI builder tool.
 
 ### Features
 - Parses arguments
-- Supports defining Positional arguments 
+- Supports defining Positional (input) arguments
   - Supports Variadic args (1 or more positional args)
 - Automatically converts flags to camelCase to match config options
   - accepts both `--camelCase` and `--kebab-case`
@@ -22,6 +22,7 @@ Simple library to create command-line tool (aka CLI) which is quite similar to [
 - Outputs description and supplied help text by using `--help`
 - Supports defining `required` options
 - Supports `default` values
+- Supports `group` for grouping command options in help
 - No dependencies!
 
 ### Install
@@ -39,11 +40,18 @@ import { type Config, parseArgs } from 'cli-nano';
 const config: Config = {
   command: {
     name: 'serve',
-    description: 'Start a server with the given options',
+    describe: 'Start a server with the given options',
+    examples: [
+      { cmd: '$0 ./www/index.html 8080 --open', describe: 'Start web server on port 8080 and open browser' },
+      {
+        cmd: '$0 ./index.html 8081 --no-open --verbose',
+        describe: 'Start web server on port 8081 without opening browser and print more debugging logging to the console',
+      },
+    ],
     positionals: [
       {
         name: 'input',
-        description: 'serving files or directory',
+        describe: 'serving files or directory',
         type: 'string',
         variadic: true, // 1 or more
         required: true,
@@ -51,62 +59,77 @@ const config: Config = {
       {
         name: 'port',
         type: 'number',
-        description: 'port to bind on',
+        describe: 'port to bind on',
         required: false,
         default: 5000, // optional default value
-      },      
+      },
     ],
   },
   options: {
     dryRun: {
       alias: 'd',
       type: 'boolean',
-      description: 'Show what would be done, but do not actually start the server',
+      describe: 'Show what would be done, but do not actually start the server',
       default: false, // optional default value
     },
+    display: {
+      group: 'Advanced Options',
+      alias: 'D',
+      required: true,
+      type: 'boolean',
+      describe: 'a required display option',
+    },
     exclude: {
       alias: 'e',
       type: 'array',
-      description: 'pattern or glob to exclude (may be passed multiple times)',
-    },
-    rainbow: {
-      type: 'boolean',
-      alias: 'r',
-      description: 'Enable rainbow mode',
-      default: true,
+      describe: 'pattern or glob to exclude (may be passed multiple times)',
     },
     verbose: {
       alias: 'V',
       type: 'boolean',
-      description: 'print more information to console',
+      describe: 'print more information to console',
+    },
+    open: {
+      alias: 'o',
+      type: 'boolean',
+      describe: 'open browser when starting server',
+      default: true,
     },
-    up: {
+    cache: {
       type: 'number',
-      description: 'slice a path off the bottom of the paths',
-      default: 1,
+      describe: 'Set cache time (in seconds) for cache-control max-age header',
+      default: 3600,
     },
-    display: {
-      alias: 'D',
+    address: {
+      type: 'string',
+      describe: 'Address to use',
       required: true,
+    },
+    rainbow: {
+      group: 'Advanced Options',
       type: 'boolean',
-      description: 'a required display option',
-    }
+      alias: 'r',
+      describe: 'Enable rainbow mode',
+      default: true,
+    },
   },
   version: '0.1.6',
-  helpOptLength: 18,  // option name length shown in help (defaults to 20)
-  helpDescLength: 60, // description length shown in help (defaults to 65)
+  helpFlagCasing: 'camel',  // show help flag option in which casing (camel/kebab) (defaults to 'kebab')
+  helpDescMinLength: 40,    // min description length shown in help (defaults to 50)
+  helpDescMaxLength: 120,   // max description length shown in help (defaults to 100), will show ellipsis (...) when greater
 };
 
 const args = parseArgs(config);
 console.log(args);
 
-// do something with parse arguments, for example
-// startServer(args);
+// do something with parsed arguments, for example
+// const { input, port, open } = args;
+// startServer({ input, port, open });
 ```
 
 ### Usage with Type Inference
 
-For full TypeScript auto-inference and IntelliSense of parsed arguments, define your config as a `const` and use `as const`:
+For full TypeScript auto-inference and intelliSense of parsed arguments, define your config as a `const` and cast it `as const`:
 
 ```ts
 const config = {
@@ -124,10 +147,10 @@ args.display; // boolean (required)
 
 > **Tip:**  
 > Using `as const` preserves literal types and tuple information, so TypeScript can infer required/optional fields and argument types automatically.  
-> If you use `const config: Config = { ... }`, you get type checking but not full IntelliSense for parsed arguments.
+> If you use `const config: Config = { ... }`, you get type checking but not full intelliSense for parsed arguments.
 
 > [!NOTE]
-> For required+variadic positionals, the type is `[string, ...string[]]` (at least one value required). For optional variadic, it's string[]. For non-variadic, it's string.
+> For required+variadic positionals, the type is `[string, ...string[]]` (at least one value required). For optional variadic, it's `string[]`. For non-variadic, it's `string`.
 
 #### Example CLI Calls
 
@@ -144,13 +167,13 @@ serve dist/index.html
 # With required and optional positionals
 serve index1.html index2.html 8080 -D value
 
-# With boolean and array options
+# With boolean and array options entered as camelCase (kebab-case works too)
 serve index.html 7000 --dryRun --exclude pattern1 --exclude pattern2 -D value
 
-# With negated boolean
+# With negated boolean entered as kebab-case
 serve index.html 7000 --no-dryRun -D value
 
-# With short aliases
+# With short aliases (case sensitive)
 serve index.html 7000 -d -e pattern1 -e pattern2 -D value
 
 # With number option
@@ -159,7 +182,7 @@ serve index.html 7000 --up 2 -D value
 
 #### Notes
 
-- **Default values**: Use the `default` property in an option or positional argument to specify a value if the user does not provide one.
+- **Default values**: Use the `default` property in an option or positional argument to specify a value when the user does not provide one.
   - Example for option: `{ type: 'boolean', default: false }`
   - Example for positional: `{ name: 'port', type: 'number', default: 5000 }`
 - **Variadic positionals**: Use `variadic: true` for arguments that accept multiple values.
@@ -167,6 +190,7 @@ serve index.html 7000 --up 2 -D value
 - **Negated booleans**: Use `--no-flag` to set a boolean option to `false`.
 - **Array options**: Repeat the flag to collect multiple values (e.g., `--exclude a --exclude b`).
 - **Aliases**: Use `alias` for short flags (e.g., `-d` for `--dryRun`).
+- **Groups**: Use `group` for grouping some commands in help (e.g., `{ group: 'Extra Commands' }`).
 
 See [examples/](examples/) for more usage patterns.
 
@@ -179,7 +203,7 @@ See [examples/](examples/) for more usage patterns.
 
 ## Help Example
 
-You can see below an example of a CLI help (which is the result of calling `--help` with the config shown avove). 
+You can see below an example of a CLI help (which is the result of calling `--help` with the [config](#usage) shown above). 
 
 Please note:
 
@@ -188,19 +212,27 @@ Please note:
 
 ```
 Usage:
-  serve <input..> [port] [options]  Start a server with the given options
+  serve <input..> [port] [options]   Start a server with the given options
+
+Examples:
+  serve ./www/index.html 8080 --open   Start web server on port 8080 and open browser
+  serve ./index.html 8081 --no-open --verbose   Start web server on port 8081 without opening browser and print more debugging logging to the console
 
 Arguments:
-  input             serving files or directory                                   <string..>
-  port              port to bind on                                              [number]
+  input           serving files or directory                                      <string..>
+  port            port to bind on                                                 [number]
 
 Options:
-  -d, --dryRun      Show what would be done, but do not actually start the se... [boolean]
-  -e, --exclude     pattern or glob to exclude (may be passed multiple times)    [array]
-  -r, --rainbow     Enable rainbow mode                                          [boolean]
-  -V, --verbose     print more information to console                            [boolean]
-      --up          slice a path off the bottom of the paths                     [number]
-  -D, --display     a required display option                                    <boolean>
-  -h, --help        Show help                                                    [boolean]
-  -v, --version     Show version number                                          [boolean]
-```
+  -d, --dry-run   Show what would be done, but do not actually start the server   [boolean]
+  -e, --exclude   pattern or glob to exclude (may be passed multiple times)       [array]
+  -V, --verbose   print more information to console                               [boolean]
+  -o, --open      open browser when starting server                               [boolean]
+      --cache     Set cache time (in seconds) for cache-control max-age header    [number]
+      --address   Address to use                                                  <string>
+  -h, --help      Show help                                                       [boolean]
+  -v, --version   Show version number                                             [boolean]
+
+Advanced Options:
+  -D, --display   a required display option                                       <boolean>
+  -r, --rainbow   Enable rainbow mode                                             [boolean]
+```

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAmB,MAAM,EAAE,MAAM,iBAAiB,CAAC;AAE3E,mBAAmB,iBAAiB,CAAC;AAOrC,wBAAgB,SAAS,CAAC,CAAC,SAAS,MAAM,EAAE,MAAM,EAAE,CAAC,GAAG,UAAU,CAAC,CAAC,CAAC,CAgMpE"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,EAAc,MAAM,iBAAiB,CAAC;AAEtE,mBAAmB,iBAAiB,CAAC;AAOrC,wBAAgB,SAAS,CAAC,CAAC,SAAS,MAAM,EAAE,MAAM,EAAE,CAAC,GAAG,UAAU,CAAC,CAAC,CAAC,CAgMpE"}

package/dist/index.js

@@ -1,6 +1,6 @@
 const defaultOptions = {
-    help: { alias: 'h', description: 'Show help', type: 'boolean' },
-    version: { alias: 'v', description: 'Show version number', type: 'boolean' },
+    help: { alias: 'h', describe: 'Show help', type: 'boolean' },
+    version: { alias: 'v', describe: 'Show version number', type: 'boolean' },
 };
 export function parseArgs(config) {
     const { command, options, version } = config;
@@ -227,22 +227,63 @@ function findOption(options, arg) {
 }
 /** Print CLI help documentation to the screen */
 function printHelp(config) {
-    const { command, options, version, helpOptLength = 20, helpDescLength = 65 } = config;
+    const { command, options, version, helpDescMinLength = 50, helpDescMaxLength = 100 } = config;
     const usagePositionals = buildUsagePositionals(command.positionals);
     console.log('Usage:');
-    console.log(`  ${command.name} ${usagePositionals} [options]  ${command.description}`);
+    console.log(`  ${command.name} ${usagePositionals} [options]   ${command.describe}`);
+    // display any examples (when provided)
+    if (Array.isArray(command.examples) && command.examples.length) {
+        console.log('\nExamples:');
+        command.examples.forEach(ex => {
+            console.log(`  ${ex.cmd.replace('$0', command.name)}   ${ex.describe || ''}`);
+        });
+    }
+    // calculate longest description length
+    let longestOptNameLn = 0;
+    let longestOptDescLn = 0;
+    for (const [key, option] of Object.entries({ ...options, ...defaultOptions })) {
+        const flagLn = (config.helpFlagCasing === 'camel' ? key : camelToKebab(key)).length;
+        if (flagLn > longestOptNameLn) {
+            longestOptNameLn = key.length;
+        }
+        if ((option.describe?.length ?? 0) > longestOptDescLn) {
+            longestOptDescLn = option.describe.length;
+        }
+    }
+    // make sure the length to use is between our defined min/max
+    if (longestOptDescLn < helpDescMinLength) {
+        longestOptDescLn = helpDescMinLength;
+    }
+    else if (longestOptDescLn > helpDescMaxLength) {
+        longestOptDescLn = helpDescMaxLength;
+    }
+    // reserve some extra spaces between option name/desc
+    longestOptDescLn += 2;
+    longestOptNameLn += 3;
     console.log('\nArguments:');
     command.positionals?.forEach(arg => {
-        console.log(`  ${formatHelpText(arg.name, helpOptLength)}${formatHelpText(arg.description, helpDescLength)} ${formatOptionType(arg.type, arg.variadic, arg.required)}`);
+        console.log(`  ${formatHelpText(arg.name, longestOptNameLn + 6)}${formatHelpText(arg.describe, longestOptDescLn)} ${formatOptionType(arg.type, arg.variadic, arg.required)}`);
     });
-    console.log('\nOptions:');
-    for (const [key, option] of Object.entries({ ...options, ...defaultOptions })) {
-        const aliasStr = option.alias ? `-${option.alias}, ` : '';
-        if (!version && key === 'version') {
-            continue;
+    // Group options by their group property
+    const groupedOptions = Object.entries({ ...options, ...defaultOptions }).reduce((acc, [key, option]) => {
+        const group = option.group || 'Options';
+        if (!acc[group]) {
+            acc[group] = [];
         }
-        console.log(`  ${aliasStr.padEnd(4)}--${formatHelpText(key, helpOptLength - 6)}${formatHelpText(option.description || '', helpDescLength)} ${formatOptionType(option.type, false, option.required)}`);
-    }
+        acc[group].push([key, option]);
+        return acc;
+    }, {});
+    Object.keys(groupedOptions).forEach(group => {
+        console.log(`\n${group}:`);
+        groupedOptions[group].forEach(([key, option]) => {
+            const aliasStr = option.alias ? `-${option.alias}, ` : '';
+            if (!version && key === 'version') {
+                return;
+            }
+            const flagName = config.helpFlagCasing === 'camel' ? key : camelToKebab(key);
+            console.log(`  ${aliasStr.padEnd(4)}--${formatHelpText(flagName, longestOptNameLn)}${formatHelpText(option.describe || '', longestOptDescLn)} ${formatOptionType(option.type, false, option.required)}`);
+        });
+    });
 }
 /** Utility to convert kebab-case to camelCase */
 function kebabToCamel(str) {

package/dist/interfaces.d.ts

@@ -1,20 +1,22 @@
-export interface ArgumentOptions {
+export interface FlagOption {
     /** option type */
     type?: 'string' | 'boolean' | 'number' | 'array';
-    /** description of the flag option */
-    description: string;
+    /** describe the flag option */
+    describe: string;
     /** defaults to undefined, provide shorter alias as command options */
     alias?: string;
     /** default value for the option if not provided */
     default?: any;
+    /** optional group for grouping some commands */
+    group?: string;
     /** defaults to false, is the option required? */
     required?: boolean;
 }
 export interface PositionalArgument {
     /** positional argument name (it will be displayed in the help docs) */
     name: string;
-    /** positional argument description */
-    description: string;
+    /** describe positional argument */
+    describe: string;
     /** postional argument type */
     type?: 'string' | 'boolean' | 'number' | 'array';
     /** defaults to false, allows multiple values for this positional argument */
@@ -24,24 +26,37 @@ export interface PositionalArgument {
     /** defaults to false, is the positional argument required? */
     required?: boolean;
 }
-export interface CommandOptions {
+export interface CommandOption {
     /** command name, used in the help docs */
     name: string;
-    /** command description */
-    description: string;
+    /** describe command */
+    describe: string;
+    /** give some example invocations of your program */
+    examples?: readonly ExampleOption[];
     /** list of positional arguments */
     positionals?: readonly PositionalArgument[];
 }
+export interface ExampleOption {
+    /** script example command, the string `$0` will get interpolated to the current script name or node command */
+    cmd: string;
+    /** describe what the script command does */
+    describe: string;
+}
 /** CLI options */
 export interface Config {
     /** CLI definition */
-    command: CommandOptions;
-    /** option name length (w/wo alias) shown in the help (defaults to 20) */
-    helpOptLength?: number;
-    /** description length shown in the help (defaults to 65) */
-    helpDescLength?: number;
+    command: CommandOption;
+    /**
+     * Show flag option in which casing (camelCase or kebab-case) in the help (defaults to 'kebab').
+     * Note: this is only for the help print, the parsing will always support both camel/kebab casing
+     */
+    helpFlagCasing?: 'camel' | 'kebab';
+    /** min description length shown in the help (defaults to 50) */
+    helpDescMinLength?: number;
+    /** max description length shown in the help (defaults to 100) */
+    helpDescMaxLength?: number;
     /** CLI list of flag options */
-    options: Record<string, ArgumentOptions>;
+    options: Record<string, FlagOption>;
     /** CLI or package version */
     version?: string;
 }

package/dist/interfaces.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"interfaces.d.ts","sourceRoot":"","sources":["../src/interfaces.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,eAAe;IAC9B,kBAAkB;IAClB,IAAI,CAAC,EAAE,QAAQ,GAAG,SAAS,GAAG,QAAQ,GAAG,OAAO,CAAC;IAEjD,qCAAqC;IACrC,WAAW,EAAE,MAAM,CAAC;IAEpB,sEAAsE;IACtE,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf,mDAAmD;IACnD,OAAO,CAAC,EAAE,GAAG,CAAC;IAEd,iDAAiD;IACjD,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED,MAAM,WAAW,kBAAkB;IACjC,uEAAuE;IACvE,IAAI,EAAE,MAAM,CAAC;IAEb,sCAAsC;IACtC,WAAW,EAAE,MAAM,CAAC;IAEpB,8BAA8B;IAC9B,IAAI,CAAC,EAAE,QAAQ,GAAG,SAAS,GAAG,QAAQ,GAAG,OAAO,CAAC;IAEjD,6EAA6E;IAC7E,QAAQ,CAAC,EAAE,OAAO,CAAC;IAEnB,mDAAmD;IACnD,OAAO,CAAC,EAAE,GAAG,CAAC;IAEd,8DAA8D;IAC9D,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED,MAAM,WAAW,cAAc;IAC7B,0CAA0C;IAC1C,IAAI,EAAE,MAAM,CAAC;IAEb,0BAA0B;IAC1B,WAAW,EAAE,MAAM,CAAC;IAEpB,mCAAmC;IACnC,WAAW,CAAC,EAAE,SAAS,kBAAkB,EAAE,CAAC;CAC7C;AAED,kBAAkB;AAClB,MAAM,WAAW,MAAM;IACrB,qBAAqB;IACrB,OAAO,EAAE,cAAc,CAAC;IAExB,yEAAyE;IACzE,aAAa,CAAC,EAAE,MAAM,CAAC;IAEvB,4DAA4D;IAC5D,cAAc,CAAC,EAAE,MAAM,CAAC;IAExB,+BAA+B;IAC/B,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC;IAEzC,6BAA6B;IAC7B,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,iFAAiF;AACjF,MAAM,MAAM,YAAY,CAAC,CAAC,SAAS;IAAE,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,GAAG,CAAC;IAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,EAAE,OAAO,CAAA;CAAE,IAAI,CAAC,CAAC,MAAM,CAAC,SAAS,SAAS,GACtI,OAAO,GACP,CAAC,CAAC,MAAM,CAAC,SAAS,QAAQ,GACxB,MAAM,GACN,CAAC,CAAC,MAAM,CAAC,SAAS,OAAO,GACvB,CAAC,SAAS;IAAE,QAAQ,EAAE,IAAI,CAAA;CAAE,GAC1B,CAAC,SAAS;IAAE,QAAQ,EAAE,IAAI,CAAA;CAAE,GAC1B,CAAC,MAAM,EAAE,GAAG,MAAM,EAAE,CAAC,GACrB,MAAM,EAAE,GACV,MAAM,GAAG,MAAM,EAAE,GACnB,CAAC,CAAC,MAAM,CAAC,SAAS,QAAQ,GACxB,CAAC,SAAS;IAAE,QAAQ,EAAE,IAAI,CAAA;CAAE,GAC1B,CAAC,SAAS;IAAE,QAAQ,EAAE,IAAI,CAAA;CAAE,GAC1B,CAAC,MAAM,EAAE,GAAG,MAAM,EAAE,CAAC,GACrB,MAAM,EAAE,GACV,MAAM,GACR,CAAC,CAAC,MAAM,CAAC,SAAS,SAAS,GACzB,CAAC,SAAS;IAAE,QAAQ,EAAE,IAAI,CAAA;CAAE,GAC1B,CAAC,SAAS;IAAE,QAAQ,EAAE,IAAI,CAAA;CAAE,GAC1B,CAAC,MAAM,EAAE,GAAG,MAAM,EAAE,CAAC,GACrB,MAAM,EAAE,GACV,MAAM,GACR,CAAC,CAAC,SAAS,CAAC,SAAS,SAAS,GAC5B,MAAM,GACN,CAAC,CAAC,SAAS,CAAC,CAAC;AAE3B,kCAAkC;AAClC,KAAK,YAAY,CAAC,CAAC,IAAI;KACpB,CAAC,IAAI,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS;QAAE,QAAQ,EAAE,IAAI,CAAA;KAAE,GAAG,CAAC,GAAG,KAAK;CAC5D,CAAC,MAAM,CAAC,CAAC,CAAC;AAEX,kCAAkC;AAClC,KAAK,YAAY,CAAC,CAAC,IAAI,OAAO,CAAC,MAAM,CAAC,EAAE,YAAY,CAAC,CAAC,CAAC,CAAC,CAAC;AAEzD,6EAA6E;AAC7E,MAAM,MAAM,eAAe,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,IAAI;KAAG,CAAC,IAAI,YAAY,CAAC,CAAC,CAAC,GAAG,YAAY,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;CAAE,GAAG;KAC3G,CAAC,IAAI,YAAY,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,YAAY,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;CAC5C,CAAC;AAEF,gFAAgF;AAChF,MAAM,MAAM,mBAAmB,CAAC,CAAC,SAAS,SAAS,kBAAkB,EAAE,GAAG,SAAS,IAAI,CAAC,SAAS,SAAS,CAAC,MAAM,CAAC,EAAE,GAAG,MAAM,IAAI,CAAC,GAC9H,CAAC,SAAS,kBAAkB,GAC1B,CAAC,CAAC,CAAC,UAAU,CAAC,SAAS,IAAI,GAAG;KAAG,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC,GAAG,YAAY,CAAC,CAAC,CAAC;CAAE,GAAG;KAAG,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,YAAY,CAAC,CAAC,CAAC;CAAE,CAAC,GAC3G,mBAAmB,CAAC,IAAI,SAAS,SAAS,kBAAkB,EAAE,GAAG,IAAI,GAAG,EAAE,CAAC,GAC7E,mBAAmB,CAAC,IAAI,SAAS,SAAS,kBAAkB,EAAE,GAAG,IAAI,GAAG,EAAE,CAAC,GAC7E;IAAE,CAAC,GAAG,EAAE,MAAM,GAAG,KAAK,CAAA;CAAE,CAAC;AAE7B,yCAAyC;AACzC,MAAM,MAAM,UAAU,CAAC,CAAC,SAAS,MAAM,IAAI,mBAAmB,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,aAAa,CAAC,CAAC,GAAG,eAAe,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC"}
+{"version":3,"file":"interfaces.d.ts","sourceRoot":"","sources":["../src/interfaces.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "cli-nano",
-  "version": "1.1.3",
-  "description": "Mini command-line tool similar to `yargs` or `parseArgs` from Node.js that accepts positional arguments, flags and options.",
+  "version": "1.2.0",
+  "description": "Small command-line tool similar to `yargs` or `parseArgs` from Node.js to create a CLI accepting positional arguments, flags and options.",
   "type": "module",
   "main": "./dist/index.js",
   "exports": {

package/src/index.ts

@@ -1,10 +1,10 @@
-import type { ArgsResult, ArgumentOptions, Config } from './interfaces.js';
+import type { ArgsResult, Config, FlagOption } from './interfaces.js';
 
 export type * from './interfaces.js';
 
-const defaultOptions: Record<string, ArgumentOptions> = {
-  help: { alias: 'h', description: 'Show help', type: 'boolean' },
-  version: { alias: 'v', description: 'Show version number', type: 'boolean' },
+const defaultOptions: Record<string, FlagOption> = {
+  help: { alias: 'h', describe: 'Show help', type: 'boolean' },
+  version: { alias: 'v', describe: 'Show version number', type: 'boolean' },
 };
 
 export function parseArgs<C extends Config>(config: C): ArgsResult<C> {
@@ -117,7 +117,7 @@ export function parseArgs<C extends Config>(config: C): ArgsResult<C> {
     }
     const argOrg = args[argIndex] || '';
     let arg = argOrg;
-    let option: ArgumentOptions | undefined;
+    let option: FlagOption | undefined;
     let configKey: string | undefined;
 
     if (argOrg.startsWith('-')) {
@@ -225,7 +225,7 @@ function formatOptionType(type: string | undefined, variadic?: boolean, required
 }
 
 /** Helper to find an option and its config key by argument name or alias. */
-function findOption(options: Record<string, ArgumentOptions>, arg: string): [ArgumentOptions | undefined, string | undefined] {
+function findOption(options: Record<string, FlagOption>, arg: string): [FlagOption | undefined, string | undefined] {
   // Try all forms: as-is, kebab-to-camel, camel-to-kebab
   const option = options[arg] || options[kebabToCamel(arg)] || options[camelToKebab(arg).replace(/-/g, '')];
   if (option) {
@@ -244,28 +244,77 @@ function findOption(options: Record<string, ArgumentOptions>, arg: string): [Arg
 
 /** Print CLI help documentation to the screen */
 function printHelp(config: Config) {
-  const { command, options, version, helpOptLength = 20, helpDescLength = 65 } = config;
+  const { command, options, version, helpDescMinLength = 50, helpDescMaxLength = 100 } = config;
   const usagePositionals = buildUsagePositionals(command.positionals);
 
   console.log('Usage:');
-  console.log(`  ${command.name} ${usagePositionals} [options]  ${command.description}`);
+  console.log(`  ${command.name} ${usagePositionals} [options]   ${command.describe}`);
+
+  // display any examples (when provided)
+  if (Array.isArray(command.examples) && command.examples.length) {
+    console.log('\nExamples:');
+    command.examples.forEach(ex => {
+      console.log(`  ${ex.cmd.replace('$0', command.name)}   ${ex.describe || ''}`);
+    });
+  }
+
+  // calculate longest description length
+  let longestOptNameLn = 0;
+  let longestOptDescLn = 0;
+  for (const [key, option] of Object.entries({ ...options, ...defaultOptions })) {
+    const flagLn = (config.helpFlagCasing === 'camel' ? key : camelToKebab(key)).length;
+    if (flagLn > longestOptNameLn) {
+      longestOptNameLn = key.length;
+    }
+    if ((option.describe?.length ?? 0) > longestOptDescLn) {
+      longestOptDescLn = option.describe.length;
+    }
+  }
+
+  // make sure the length to use is between our defined min/max
+  if (longestOptDescLn < helpDescMinLength) {
+    longestOptDescLn = helpDescMinLength;
+  } else if (longestOptDescLn > helpDescMaxLength) {
+    longestOptDescLn = helpDescMaxLength;
+  }
+
+  // reserve some extra spaces between option name/desc
+  longestOptDescLn += 2;
+  longestOptNameLn += 3;
+
   console.log('\nArguments:');
   command.positionals?.forEach(arg => {
     console.log(
-      `  ${formatHelpText(arg.name, helpOptLength)}${formatHelpText(arg.description, helpDescLength)} ${formatOptionType(arg.type, arg.variadic, arg.required)}`,
+      `  ${formatHelpText(arg.name, longestOptNameLn + 6)}${formatHelpText(arg.describe, longestOptDescLn)} ${formatOptionType(arg.type, arg.variadic, arg.required)}`,
     );
   });
 
-  console.log('\nOptions:');
-  for (const [key, option] of Object.entries({ ...options, ...defaultOptions })) {
-    const aliasStr = option.alias ? `-${option.alias}, ` : '';
-    if (!version && key === 'version') {
-      continue;
-    }
-    console.log(
-      `  ${aliasStr.padEnd(4)}--${formatHelpText(key, helpOptLength - 6)}${formatHelpText(option.description || '', helpDescLength)} ${formatOptionType(option.type, false, option.required)}`,
-    );
-  }
+  // Group options by their group property
+  const groupedOptions = Object.entries({ ...options, ...defaultOptions }).reduce(
+    (acc, [key, option]) => {
+      const group = option.group || 'Options';
+      if (!acc[group]) {
+        acc[group] = [];
+      }
+      acc[group].push([key, option]);
+      return acc;
+    },
+    {} as Record<string, [string, FlagOption][]>,
+  );
+
+  Object.keys(groupedOptions).forEach(group => {
+    console.log(`\n${group}:`);
+    groupedOptions[group].forEach(([key, option]) => {
+      const aliasStr = option.alias ? `-${option.alias}, ` : '';
+      if (!version && key === 'version') {
+        return;
+      }
+      const flagName = config.helpFlagCasing === 'camel' ? key : camelToKebab(key);
+      console.log(
+        `  ${aliasStr.padEnd(4)}--${formatHelpText(flagName, longestOptNameLn)}${formatHelpText(option.describe || '', longestOptDescLn)} ${formatOptionType(option.type, false, option.required)}`,
+      );
+    });
+  });
 }
 
 /** Utility to convert kebab-case to camelCase */

package/src/interfaces.ts

@@ -1,9 +1,9 @@
-export interface ArgumentOptions {
+export interface FlagOption {
   /** option type */
   type?: 'string' | 'boolean' | 'number' | 'array';
 
-  /** description of the flag option */
-  description: string;
+  /** describe the flag option */
+  describe: string;
 
   /** defaults to undefined, provide shorter alias as command options */
   alias?: string;
@@ -11,6 +11,9 @@ export interface ArgumentOptions {
   /** default value for the option if not provided */
   default?: any;
 
+  /** optional group for grouping some commands */
+  group?: string;
+
   /** defaults to false, is the option required? */
   required?: boolean;
 }
@@ -19,8 +22,8 @@ export interface PositionalArgument {
   /** positional argument name (it will be displayed in the help docs) */
   name: string;
 
-  /** positional argument description */
-  description: string;
+  /** describe positional argument */
+  describe: string;
 
   /** postional argument type */
   type?: 'string' | 'boolean' | 'number' | 'array';
@@ -35,30 +38,47 @@ export interface PositionalArgument {
   required?: boolean;
 }
 
-export interface CommandOptions {
+export interface CommandOption {
   /** command name, used in the help docs */
   name: string;
 
-  /** command description */
-  description: string;
+  /** describe command */
+  describe: string;
+
+  /** give some example invocations of your program */
+  examples?: readonly ExampleOption[];
 
   /** list of positional arguments */
   positionals?: readonly PositionalArgument[];
 }
 
+export interface ExampleOption {
+  /** script example command, the string `$0` will get interpolated to the current script name or node command */
+  cmd: string;
+
+  /** describe what the script command does */
+  describe: string;
+}
+
 /** CLI options */
 export interface Config {
   /** CLI definition */
-  command: CommandOptions;
+  command: CommandOption;
+
+  /**
+   * Show flag option in which casing (camelCase or kebab-case) in the help (defaults to 'kebab').
+   * Note: this is only for the help print, the parsing will always support both camel/kebab casing
+   */
+  helpFlagCasing?: 'camel' | 'kebab';
 
-  /** option name length (w/wo alias) shown in the help (defaults to 20) */
-  helpOptLength?: number;
+  /** min description length shown in the help (defaults to 50) */
+  helpDescMinLength?: number;
 
-  /** description length shown in the help (defaults to 65) */
-  helpDescLength?: number;
+  /** max description length shown in the help (defaults to 100) */
+  helpDescMaxLength?: number;
 
   /** CLI list of flag options */
-  options: Record<string, ArgumentOptions>;
+  options: Record<string, FlagOption>;
 
   /** CLI or package version */
   version?: string;