cli-nano 1.2.2 → 1.3.1

package/README.md

@@ -4,7 +4,7 @@
 [![codecov](https://codecov.io/gh/ghiscoding/cli-nano/branch/main/graph/badge.svg)](https://codecov.io/gh/ghiscoding/cli-nano)
 [![npm](https://img.shields.io/npm/v/cli-nano.svg)](https://www.npmjs.com/package/cli-nano)
 [![npm](https://img.shields.io/npm/dy/cli-nano)](https://www.npmjs.com/package/cli-nano)
-[![npm bundle size](https://img.shields.io/bundlephobia/minzip/cli-nano?color=success&label=gzip)](https://bundlephobia.com/result?p=cli-nano)
+[![npm bundle size](https://img.shields.io/badge/gzip-2.5kB-1183c4)](https://bundlejs.com/?q=cli-nano)
 <a href="https://nodejs.org/en/about/previous-releases"><img src="https://img.shields.io/node/v/cli-nano.svg" alt="Node" /></a>
 
 ## cli-nano
@@ -13,8 +13,8 @@ Small library to create command-line tool (aka CLI) which is quite similar to [`
 
 ### Features
 - Parses arguments
-- Supports defining Positional (input) arguments
-  - Supports Variadic args (1 or more positional args)
+- Supports defining Positional arguments (input args)
+  - Supports Variadic arguments (1 or more positional args)
 - Automatically converts flags to camelCase to match config options
   - accepts both `--camelCase` and `--kebab-case`
 - Negates flags when using the `--no-` prefix
@@ -23,7 +23,24 @@ Small library to create command-line tool (aka CLI) which is quite similar to [`
 - Supports defining `required` options
 - Supports `default` values
 - Supports `group` for grouping command options in help
-- No dependencies!
+- No dependencies and very lightweight!
+
+### Recent additions
+
+- Grouped short flags: support clustered short aliases (e.g. `-ad`) where the last short may consume a value when appropriate.
+- Kebab/camel duplication: parsed options are available under both `camelCase` and `kebab-case` keys (e.g. both `dryRun` and `dry-run`).
+- `--` passthrough: tokens after `--` are exposed on `result['--']` and are not parsed as options.
+- Raw argv exposure: the original argv slice is available on `result.__rawArgs` for diagnostics or passthrough adapters.
+- Bare long-form behavior: a bare long option is treated as an empty value (e.g. `--opt` → `''`) and a bare long array option becomes `['']`.
+- Boolean negation parity: negated booleans expose both `noFoo` and `no-foo` keys (e.g. `--no-dry-run` sets `dryRun=false` and also exposes `noDryRun=true` and `no-dry-run=true`).
+- Negation guard: single-dash forms like `-no-foo` / `-noFoo` are treated as negated long options rather than short clusters.
+- Error message consistency: option/argument errors use the `Unknown argument: X` wording to match existing positional error messages.
+
+Short examples:
+
+- Clustered short flags: `-ad` behaves like `-a -d` and `-ab value` lets `b` consume `value` when `b` expects a value.
+- Bare long option: `--bar` (with no following token) results in `bar: ''` for string options.
+
 
 ### Install
 ```sh
@@ -124,8 +141,8 @@ const args = parseArgs(config);
 console.log(args);
 
 // do something with parsed arguments, for example
-// const { input, port, open } = args;
-// startServer({ input, port, open });
+const { input, port, open } = args;
+startServer({ input, port, open });
 ```
 
 ### Usage with Type Inference
@@ -141,8 +158,8 @@ const args = parseArgs<typeof config>(config);
 
 // TypeScript will infer the correct types:
 args.input;   // [string, ...string[]] (required, variadic)
-args.port;    // number   (optional, has default)
-args.verbose; // boolean  (optional)
+args.port;    // number  (optional, has default)
+args.verbose; // boolean (optional)
 args.display; // boolean (required)
 ```
 
@@ -151,12 +168,12 @@ args.display; // boolean (required)
 > 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[]`. And Finally for non-variadic, it's `string`.
 
 #### Example CLI Calls
 
 ```sh
-# Show help guide (created by reading CLI config)
+# Show help guide (creates it by reading CLI config)
 serve --help
 
 # Show version (when defined)
@@ -165,7 +182,7 @@ serve --version
 # Uses default port 5000
 serve dist/index.html
 
-# With required and optional positionals
+# With required and optional positional args
 serve index1.html index2.html 8080 -D value
 
 # With boolean and array options entered as camelCase (kebab-case works too)
@@ -179,6 +196,19 @@ serve index.html 7000 -d -e pattern1 -e pattern2 -D value
 
 # With number option
 serve index.html 7000 --up 2 -D value
+
+# Clustered short flags / last-short consumption
+serve index.html 7000 -ad
+serve index.html 7000 -ab value
+
+# Equals form and bare-long
+serve index.html 7000 --opt=value
+serve index.html 7000 --opt=
+serve index.html 7000 --bar
+
+# Negation parity and passthrough
+serve index.html 7000 --no-dry-run
+serve index.html 7000 -- file.txt --not-a-flag
 ```
 
 #### Notes
@@ -193,20 +223,19 @@ serve index.html 7000 --up 2 -D value
 - **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.
-
-## Used by
+- **Equals form**: `--opt=value` and `--opt=` are supported; an empty value after `=` yields an empty string.
+- **Passthrough**: Tokens after `--` are not parsed and are available on `result['--']`.
+- **Raw argv**: The original argv slice is available on `result.__rawArgs` for diagnostics or passthrough adapters.
+- **Negation duplicates**: Using `--no-foo` sets `foo=false` and also exposes `noFoo` and `no-foo` keys.
+- **Alias**: `alias` must be a single string (multi-char aliases are supported). Array-style aliases are not supported and will be rejected.
 
-`cli-nano` is currently being used by the following projects, which is actually why I created this CLI tool, that I currently maintain as well (feel free to edit this list):
-
-- [native-copyfiles](https://github.com/ghiscoding/native-copyfiles)
-- [remove-glob](https://github.com/ghiscoding/remove-glob)
+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](#usage) shown above). 
 
-Please note that the following means:
+Please note the following expectations:
 
 - `<option>` → required
 - `[option]` → optional
@@ -237,3 +266,10 @@ Advanced Options:
   -D, --display   a required display option                                       <boolean>
   -r, --rainbow   Enable rainbow mode                                             [boolean]
 ```
+
+## Used by
+
+`cli-nano` is currently being used by the following projects, which is actually why I created this CLI tool, that I currently maintain as well (feel free to edit this list):
+
+- [native-copyfiles](https://github.com/ghiscoding/native-copyfiles)
+- [remove-glob](https://github.com/ghiscoding/remove-glob)

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,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"}
+{"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,CAuVpE"}

package/dist/index.js

@@ -4,14 +4,22 @@ const defaultOptions = {
 };
 export function parseArgs(config) {
     const { command, options, version } = config;
+    // Capture raw argv for consumers/diagnostics
+    const __rawArgs = process.argv.slice(2);
     // Normalize args to support --option=value and -o=value
-    const args = process.argv.slice(2).flatMap(arg => {
+    let args = __rawArgs.flatMap(arg => {
         if (/^--?\w[\w-]*=/.test(arg)) {
             const [flag, ...rest] = arg.split('=');
             return [flag, rest.join('=')];
         }
         return arg;
     });
+    // Capture `--` passthrough (everything after `--`) and remove from args to avoid parsing
+    const dashIndex = args.indexOf('--');
+    const dashArgs = dashIndex >= 0 ? args.slice(dashIndex + 1) : [];
+    if (dashIndex >= 0) {
+        args = args.slice(0, dashIndex);
+    }
     const result = {};
     // Check for duplicate aliases
     const aliasMap = new Map();
@@ -116,8 +124,71 @@ export function parseArgs(config) {
                 [option, configKey] = findOption(options, arg);
             }
             else if (argOrg.startsWith('-')) {
-                arg = argOrg.slice(1);
-                [option, configKey] = findOption(options, arg);
+                // Support grouped short flags, e.g. `-ab` where `a` and `b` are aliases.
+                // The last short in the cluster may consume the next token as its value
+                // when it's not a boolean option.
+                const body = argOrg.slice(1);
+                arg = body;
+                // If this exact token matches an option (rare), prefer that (e.g. -xy where xy is alias)
+                [option, configKey] = findOption(options, body);
+                // Avoid treating `-no-foo` or `-noFoo` as a short-char cluster — those are
+                // negated long forms and should be handled by the negation branch below.
+                if (!option && body.length > 1 && !/^no-/.test(body) && !/^no[A-Z]/.test(body)) {
+                    // Treat as a cluster of single-char aliases
+                    const chars = body.split('');
+                    for (let ci = 0; ci < chars.length; ci++) {
+                        const ch = chars[ci];
+                        const isLast = ci === chars.length - 1;
+                        const [cOpt, cKey] = findOption(options, ch);
+                        if (!cOpt || !cKey) {
+                            throw new Error(`Unknown argument: ${ch}`);
+                        }
+                        if (!isLast) {
+                            // Middle flags must be boolean
+                            if (cOpt.type !== 'boolean') {
+                                throw new Error(`Missing value for option: ${cKey}`);
+                            }
+                            if (result[cKey] !== undefined) {
+                                throw new Error('Providing same negated and truthy argument are not allowed');
+                            }
+                            result[cKey] = true;
+                        }
+                        else {
+                            // Last flag: if boolean, set true; otherwise consume next token as its value
+                            if (cOpt.type === 'boolean') {
+                                if (result[cKey] !== undefined) {
+                                    throw new Error('Providing same negated and truthy argument are not allowed');
+                                }
+                                result[cKey] = true;
+                            }
+                            else if (cOpt.type === 'number') {
+                                if (args[argIndex + 1] === undefined || args[argIndex + 1].startsWith('-')) {
+                                    throw new Error(`Missing value for option: ${cKey}`);
+                                }
+                                result[cKey] = Number(args[++argIndex]);
+                            }
+                            else if (cOpt.type === 'array') {
+                                if (!result[cKey]) {
+                                    result[cKey] = [];
+                                }
+                                const arrayValue = args[++argIndex];
+                                if (arrayValue === undefined || arrayValue.startsWith('-')) {
+                                    throw new Error(`Missing value for array option: ${cKey}`);
+                                }
+                                result[cKey].push(arrayValue);
+                            }
+                            else {
+                                if (args[argIndex + 1] === undefined || args[argIndex + 1].startsWith('-')) {
+                                    throw new Error(`Missing value for option: ${cKey}`);
+                                }
+                                result[cKey] = args[++argIndex];
+                            }
+                        }
+                    }
+                    // We've consumed any value for the last short (if present), continue to next arg
+                    argIndex++;
+                    continue;
+                }
             }
             // Handle negated boolean in both forms
             if (!option) {
@@ -131,12 +202,24 @@ export function parseArgs(config) {
                         throw new Error('Providing same negated and truthy argument are not allowed');
                     }
                     result[configKey] = !isNegated;
+                    // When explicitly negated (e.g. --no-foo) also expose `noFoo` and `no-foo` keys
+                    if (isNegated) {
+                        const kebabKey = camelToKebab(configKey);
+                        const noCamel = `no${configKey[0].toUpperCase()}${configKey.slice(1)}`;
+                        const noKebab = `no-${kebabKey}`;
+                        if (result[noCamel] === undefined) {
+                            result[noCamel] = true;
+                        }
+                        if (result[noKebab] === undefined) {
+                            result[noKebab] = true;
+                        }
+                    }
                     argIndex++;
                     continue;
                 }
             }
             if (!option || !configKey) {
-                throw new Error(`Unknown CLI option: ${arg}`);
+                throw new Error(`Unknown argument: ${arg}`);
             }
             switch (option.type) {
                 case 'boolean':
@@ -144,6 +227,18 @@ export function parseArgs(config) {
                         throw new Error('Providing same negated and truthy argument are not allowed');
                     }
                     result[configKey] = !argOrg.startsWith('--no-') && !argOrg.startsWith('-no-');
+                    // When a boolean was explicitly negated, also expose `noFoo` and `no-foo` keys
+                    if (result[configKey] === false) {
+                        const kebabKey = camelToKebab(configKey);
+                        const noCamel = `no${configKey[0].toUpperCase()}${configKey.slice(1)}`;
+                        const noKebab = `no-${kebabKey}`;
+                        if (result[noCamel] === undefined) {
+                            result[noCamel] = true;
+                        }
+                        if (result[noKebab] === undefined) {
+                            result[noKebab] = true;
+                        }
+                    }
                     break;
                 case 'number':
                     if (args[argIndex + 1] === undefined || args[argIndex + 1].startsWith('-')) {
@@ -152,21 +247,38 @@ export function parseArgs(config) {
                     result[configKey] = Number(args[++argIndex]);
                     break;
                 case 'array': {
-                    if (!result[configKey])
+                    if (!result[configKey]) {
                         result[configKey] = [];
-                    const arrayValue = args[++argIndex];
-                    if (arrayValue === undefined || arrayValue.startsWith('-')) {
-                        throw new Error(`Missing value for array option: ${configKey}`);
                     }
-                    result[configKey].push(arrayValue);
+                    const next = args[argIndex + 1];
+                    if (next === undefined || next.startsWith('-')) {
+                        // For bare long-form options we allow empty value; short/clustered forms still throw
+                        if (argOrg.startsWith('--')) {
+                            result[configKey].push('');
+                        }
+                        else {
+                            throw new Error(`Missing value for array option: ${configKey}`);
+                        }
+                    }
+                    else {
+                        result[configKey].push(args[++argIndex]);
+                    }
                     break;
                 }
                 case 'string':
                 default:
                     if (args[argIndex + 1] === undefined || args[argIndex + 1].startsWith('-')) {
-                        throw new Error(`Missing value for option: ${configKey}`);
+                        if (argOrg.startsWith('--')) {
+                            // treat bare long option as empty string
+                            result[configKey] = '';
+                        }
+                        else {
+                            throw new Error(`Missing value for option: ${configKey}`);
+                        }
+                    }
+                    else {
+                        result[configKey] = args[++argIndex];
                     }
-                    result[configKey] = args[++argIndex];
                     break;
             }
         }
@@ -175,17 +287,55 @@ export function parseArgs(config) {
         }
         argIndex++;
     }
-    // After all parsing, assign any `default` CLI options when undefined
-    // and check for any missing `required` CLI options
+    // After all parsing, first ensure any `required` CLI options are present
+    // (required should error even for boolean flags). Then assign any
+    // explicit `default` values and finally apply yargs-parity boolean
+    // defaults for non-required boolean flags.
     Object.entries(options).forEach(([key, opt]) => {
-        if (result[key] === undefined && opt.default !== undefined) {
-            result[key] = opt.default;
-        }
-        if (opt.required && result[key] === undefined) {
+        // If the option wasn't provided and is required, throw immediately.
+        if (result[key] === undefined && opt.required) {
             const aliasStr = opt.alias ? `-${opt.alias}, ` : '';
             throw new Error(`Missing required option: ${aliasStr}--${key}`);
         }
+        // If the option wasn't provided, apply any explicit default.
+        if (result[key] === undefined) {
+            if (opt.default !== undefined) {
+                result[key] = opt.default;
+            }
+            else if (opt.type === 'boolean') {
+                // Parity with yargs: boolean flags default to false when not provided
+                result[key] = false;
+            }
+        }
     });
+    // Expose raw non-option positionals as `._` for convenience
+    if (result._ === undefined) {
+        result._ = nonOptionArgs.slice();
+    }
+    // Duplicate parsed keys into both kebab-case and camelCase for parity with yargs.
+    // Use a snapshot of keys to avoid iterating over newly-created duplicates.
+    const parsedKeys = Object.keys(result);
+    for (const key of parsedKeys) {
+        if (key === '--' || key === '__rawArgs') {
+            continue;
+        }
+        const value = result[key];
+        const kebab = camelToKebab(key);
+        const camel = kebabToCamel(key);
+        if (kebab !== key && result[kebab] === undefined) {
+            result[kebab] = value;
+        }
+        if (camel !== key && result[camel] === undefined) {
+            result[camel] = value;
+        }
+    }
+    // Expose passthrough tokens and raw args for downstream consumers
+    if (!result['--']) {
+        result['--'] = dashArgs.slice();
+    }
+    if (result.__rawArgs === undefined) {
+        result.__rawArgs = __rawArgs.slice();
+    }
     return result;
 }
 /** Format a text to a fixed length, truncating and padding as needed. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cli-nano",
-  "version": "1.2.2",
+  "version": "1.3.1",
   "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",

package/src/index.ts

@@ -10,14 +10,24 @@ const defaultOptions: Record<string, FlagOption> = {
 export function parseArgs<C extends Config>(config: C): ArgsResult<C> {
   const { command, options, version } = config;
 
+  // Capture raw argv for consumers/diagnostics
+  const __rawArgs = process.argv.slice(2);
+
   // Normalize args to support --option=value and -o=value
-  const args = process.argv.slice(2).flatMap(arg => {
+  let args = __rawArgs.flatMap(arg => {
     if (/^--?\w[\w-]*=/.test(arg)) {
       const [flag, ...rest] = arg.split('=');
       return [flag, rest.join('=')];
     }
     return arg;
   });
+
+  // Capture `--` passthrough (everything after `--`) and remove from args to avoid parsing
+  const dashIndex = args.indexOf('--');
+  const dashArgs: string[] = dashIndex >= 0 ? args.slice(dashIndex + 1) : [];
+  if (dashIndex >= 0) {
+    args = args.slice(0, dashIndex);
+  }
   const result: Record<string, any> = {};
 
   // Check for duplicate aliases
@@ -125,8 +135,70 @@ export function parseArgs<C extends Config>(config: C): ArgsResult<C> {
         arg = argOrg.slice(2);
         [option, configKey] = findOption(options, arg);
       } else if (argOrg.startsWith('-')) {
-        arg = argOrg.slice(1);
-        [option, configKey] = findOption(options, arg);
+        // Support grouped short flags, e.g. `-ab` where `a` and `b` are aliases.
+        // The last short in the cluster may consume the next token as its value
+        // when it's not a boolean option.
+        const body = argOrg.slice(1);
+        arg = body;
+
+        // If this exact token matches an option (rare), prefer that (e.g. -xy where xy is alias)
+        [option, configKey] = findOption(options, body);
+        // Avoid treating `-no-foo` or `-noFoo` as a short-char cluster — those are
+        // negated long forms and should be handled by the negation branch below.
+        if (!option && body.length > 1 && !/^no-/.test(body) && !/^no[A-Z]/.test(body)) {
+          // Treat as a cluster of single-char aliases
+          const chars = body.split('');
+          for (let ci = 0; ci < chars.length; ci++) {
+            const ch = chars[ci];
+            const isLast = ci === chars.length - 1;
+            const [cOpt, cKey] = findOption(options, ch);
+            if (!cOpt || !cKey) {
+              throw new Error(`Unknown argument: ${ch}`);
+            }
+
+            if (!isLast) {
+              // Middle flags must be boolean
+              if (cOpt.type !== 'boolean') {
+                throw new Error(`Missing value for option: ${cKey}`);
+              }
+              if (result[cKey] !== undefined) {
+                throw new Error('Providing same negated and truthy argument are not allowed');
+              }
+              result[cKey] = true;
+            } else {
+              // Last flag: if boolean, set true; otherwise consume next token as its value
+              if (cOpt.type === 'boolean') {
+                if (result[cKey] !== undefined) {
+                  throw new Error('Providing same negated and truthy argument are not allowed');
+                }
+                result[cKey] = true;
+              } else if (cOpt.type === 'number') {
+                if (args[argIndex + 1] === undefined || args[argIndex + 1].startsWith('-')) {
+                  throw new Error(`Missing value for option: ${cKey}`);
+                }
+                result[cKey] = Number(args[++argIndex]);
+              } else if (cOpt.type === 'array') {
+                if (!result[cKey]) {
+                  result[cKey] = [];
+                }
+                const arrayValue = args[++argIndex];
+                if (arrayValue === undefined || arrayValue.startsWith('-')) {
+                  throw new Error(`Missing value for array option: ${cKey}`);
+                }
+                result[cKey].push(arrayValue);
+              } else {
+                if (args[argIndex + 1] === undefined || args[argIndex + 1].startsWith('-')) {
+                  throw new Error(`Missing value for option: ${cKey}`);
+                }
+                result[cKey] = args[++argIndex];
+              }
+            }
+          }
+
+          // We've consumed any value for the last short (if present), continue to next arg
+          argIndex++;
+          continue;
+        }
       }
 
       // Handle negated boolean in both forms
@@ -141,13 +213,25 @@ export function parseArgs<C extends Config>(config: C): ArgsResult<C> {
             throw new Error('Providing same negated and truthy argument are not allowed');
           }
           result[configKey] = !isNegated;
+          // When explicitly negated (e.g. --no-foo) also expose `noFoo` and `no-foo` keys
+          if (isNegated) {
+            const kebabKey = camelToKebab(configKey);
+            const noCamel = `no${configKey[0].toUpperCase()}${configKey.slice(1)}`;
+            const noKebab = `no-${kebabKey}`;
+            if (result[noCamel] === undefined) {
+              result[noCamel] = true;
+            }
+            if (result[noKebab] === undefined) {
+              result[noKebab] = true;
+            }
+          }
           argIndex++;
           continue;
         }
       }
 
       if (!option || !configKey) {
-        throw new Error(`Unknown CLI option: ${arg}`);
+        throw new Error(`Unknown argument: ${arg}`);
       }
 
       switch (option.type) {
@@ -156,6 +240,18 @@ export function parseArgs<C extends Config>(config: C): ArgsResult<C> {
             throw new Error('Providing same negated and truthy argument are not allowed');
           }
           result[configKey] = !argOrg.startsWith('--no-') && !argOrg.startsWith('-no-');
+          // When a boolean was explicitly negated, also expose `noFoo` and `no-foo` keys
+          if (result[configKey] === false) {
+            const kebabKey = camelToKebab(configKey);
+            const noCamel = `no${configKey[0].toUpperCase()}${configKey.slice(1)}`;
+            const noKebab = `no-${kebabKey}`;
+            if (result[noCamel] === undefined) {
+              result[noCamel] = true;
+            }
+            if (result[noKebab] === undefined) {
+              result[noKebab] = true;
+            }
+          }
           break;
         case 'number':
           if (args[argIndex + 1] === undefined || args[argIndex + 1].startsWith('-')) {
@@ -164,20 +260,34 @@ export function parseArgs<C extends Config>(config: C): ArgsResult<C> {
           result[configKey] = Number(args[++argIndex]);
           break;
         case 'array': {
-          if (!result[configKey]) result[configKey] = [];
-          const arrayValue = args[++argIndex];
-          if (arrayValue === undefined || arrayValue.startsWith('-')) {
-            throw new Error(`Missing value for array option: ${configKey}`);
+          if (!result[configKey]) {
+            result[configKey] = [];
+          }
+          const next = args[argIndex + 1];
+          if (next === undefined || next.startsWith('-')) {
+            // For bare long-form options we allow empty value; short/clustered forms still throw
+            if (argOrg.startsWith('--')) {
+              result[configKey].push('');
+            } else {
+              throw new Error(`Missing value for array option: ${configKey}`);
+            }
+          } else {
+            result[configKey].push(args[++argIndex]);
           }
-          result[configKey].push(arrayValue);
           break;
         }
         case 'string':
         default:
           if (args[argIndex + 1] === undefined || args[argIndex + 1].startsWith('-')) {
-            throw new Error(`Missing value for option: ${configKey}`);
+            if (argOrg.startsWith('--')) {
+              // treat bare long option as empty string
+              result[configKey] = '';
+            } else {
+              throw new Error(`Missing value for option: ${configKey}`);
+            }
+          } else {
+            result[configKey] = args[++argIndex];
           }
-          result[configKey] = args[++argIndex];
           break;
       }
     } else {
@@ -186,18 +296,59 @@ export function parseArgs<C extends Config>(config: C): ArgsResult<C> {
     argIndex++;
   }
 
-  // After all parsing, assign any `default` CLI options when undefined
-  // and check for any missing `required` CLI options
+  // After all parsing, first ensure any `required` CLI options are present
+  // (required should error even for boolean flags). Then assign any
+  // explicit `default` values and finally apply yargs-parity boolean
+  // defaults for non-required boolean flags.
   Object.entries(options).forEach(([key, opt]) => {
-    if (result[key] === undefined && opt.default !== undefined) {
-      result[key] = opt.default;
-    }
-    if (opt.required && result[key] === undefined) {
+    // If the option wasn't provided and is required, throw immediately.
+    if (result[key] === undefined && opt.required) {
       const aliasStr = opt.alias ? `-${opt.alias}, ` : '';
       throw new Error(`Missing required option: ${aliasStr}--${key}`);
     }
+
+    // If the option wasn't provided, apply any explicit default.
+    if (result[key] === undefined) {
+      if (opt.default !== undefined) {
+        result[key] = opt.default;
+      } else if (opt.type === 'boolean') {
+        // Parity with yargs: boolean flags default to false when not provided
+        result[key] = false;
+      }
+    }
   });
 
+  // Expose raw non-option positionals as `._` for convenience
+  if ((result as any)._ === undefined) {
+    (result as any)._ = nonOptionArgs.slice();
+  }
+
+  // Duplicate parsed keys into both kebab-case and camelCase for parity with yargs.
+  // Use a snapshot of keys to avoid iterating over newly-created duplicates.
+  const parsedKeys = Object.keys(result);
+  for (const key of parsedKeys) {
+    if (key === '--' || key === '__rawArgs') {
+      continue;
+    }
+    const value = result[key];
+    const kebab = camelToKebab(key);
+    const camel = kebabToCamel(key);
+    if (kebab !== key && result[kebab] === undefined) {
+      result[kebab] = value;
+    }
+    if (camel !== key && result[camel] === undefined) {
+      result[camel] = value;
+    }
+  }
+
+  // Expose passthrough tokens and raw args for downstream consumers
+  if (!result['--']) {
+    result['--'] = dashArgs.slice();
+  }
+  if ((result as any).__rawArgs === undefined) {
+    (result as any).__rawArgs = __rawArgs.slice();
+  }
+
   return result as ArgsResult<C>;
 }