cli-nano 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+Copyright (c) 2024-present, Ghislain B.
+https://github.com/ghiscoding/gc-utils/frameworks/release
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,124 @@
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![TypeScript](https://img.shields.io/badge/%3C%2F%3E-TypeScript-%230074c1.svg)](http://www.typescriptlang.org/)
+[![Vitest](https://img.shields.io/badge/tested%20with-vitest-fcc72b.svg?logo=vitest)](https://vitest.dev/)
+[![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)
+
+## cli-nano
+
+Super small custom CLI similar to `Yargs` but much smaller, it uses a similar approach to NodeJS `parseArgs()` to create command-line tool (aka CLI). It is much more complete than NodeJS `parseArgs()` since it supports Positional Arguments, negated flags and also accepts both syntax `--camelCase` and/or `--kebab-case`.
+
+### Features
+- Parses arguments
+- Converts flags to camelCase
+- Negates flags when using the `--no-` prefix
+- Outputs version when `--version`
+- Outputs description and supplied help text when `--help`
+- No dependencies!
+
+### Install
+```sh
+npm install cli-nano
+```
+
+### Usage
+
+```ts
+#!/usr/bin/env node
+
+import { type Config, parseArgs } from 'cli-nano';
+
+const config: Config = {
+  command: {
+    name: 'unicorns',
+    description: 'Show a list of unicorns',
+    positional: [
+      {
+        name: 'inputs',
+        description: 'unicorn inputs',
+        type: 'string',
+        variadic: true, // one or more inputs could be provided
+        required: true,
+      },
+      {
+        name: 'output',
+        description: 'output directory',
+        type: 'string',
+        required: false,
+      },
+    ],
+  },
+  options: {
+    dryRun: {
+      alias: 'd',
+      type: 'boolean',
+      description: 'Show what would be copied, but do not actually copy any files',
+    },
+    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',
+    },
+    verbose: {
+      alias: 'V',
+      type: 'boolean',
+      description: 'print more information to console',
+    },
+    up: {
+      type: 'number',
+      description: 'slice a path off the bottom of the paths',
+    },
+    bar: {
+      alias: 'b',
+      required: true,
+      description: 'a required bar option',
+    }
+  },
+  version: '0.1.6',
+};
+
+const argv = parseArgs(config);
+console.log(argv);
+```
+
+#### Example CLI Calls
+
+```sh
+# Show help
+unicorns --help
+
+# Show version
+unicorns --version
+
+# With required and optional positionals
+unicorns file1.txt file2.txt output/ -b value
+
+# With boolean and array options
+unicorns file1.txt output/ --dryRun --exclude pattern1 --exclude pattern2 -b value
+
+# With negated boolean
+unicorns file1.txt output/ --no-dryRun -b value
+
+# With short aliases
+unicorns file1.txt output/ -d -e pattern1 -e pattern2 -b value
+
+# With number option
+unicorns file1.txt output/ --up 2 -b value
+```
+
+#### Notes
+
+- **Variadic positionals**: Use `variadic: true` for arguments that accept multiple values.
+- **Required options**: Add `required: true` to enforce presence of an option.
+- **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`).
+
+See [examples/](examples/) for more usage patterns.

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+import type { Config } from './interfaces.js';
+export declare function parseArgs(config: Config): Record<string, any>;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAmB,MAAM,EAAE,MAAM,iBAAiB,CAAC;AAG/D,wBAAgB,SAAS,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAqM7D"}

package/dist/index.js

@@ -0,0 +1,225 @@
+import { camelToKebab, kebabToCamel, padString } from './utils.js';
+export function parseArgs(config) {
+    const { command, options, version } = config;
+    const args = process.argv.slice(2);
+    const result = {};
+    // Check for duplicate aliases
+    const aliasMap = new Map();
+    for (const [key, opt] of Object.entries(options)) {
+        if (opt.alias) {
+            const optAlias = opt.alias;
+            if (aliasMap.has(optAlias)) {
+                throw new Error(`Duplicate alias detected: "${opt.alias}" used for both "${aliasMap.get(optAlias)}" and "${key}"`);
+            }
+            aliasMap.set(optAlias, key);
+        }
+    }
+    // Handle --help and --version before anything else
+    if (args.includes('--help') || args.includes('-h')) {
+        printHelp(config);
+        process.exit(0);
+    }
+    if (args.includes('--version') || args.includes('-v')) {
+        console.log(version);
+        process.exit(0);
+    }
+    // Handle positional arguments
+    let argIndex = 0;
+    const positionals = command.positional ?? [];
+    const nonOptionArgs = [];
+    while (argIndex < args.length && !args[argIndex].startsWith('-')) {
+        nonOptionArgs.push(args[argIndex]);
+        argIndex++;
+    }
+    let nonOptionIndex = 0;
+    for (let i = 0; i < positionals.length; i++) {
+        const pos = positionals[i];
+        if (pos.variadic) {
+            const remaining = positionals.length - (i + 1);
+            const values = nonOptionArgs.slice(nonOptionIndex, nonOptionArgs.length - remaining);
+            if (pos.required && values.length === 0) {
+                const usagePositionals = positionals.map(posArg => `<${posArg.name}>`).join(' ');
+                throw new Error(`Missing required positional argument, i.e.: "${command.name} ${usagePositionals}"`);
+            }
+            result[pos.name] = values;
+            nonOptionIndex += values.length;
+        }
+        else {
+            const value = nonOptionArgs[nonOptionIndex++];
+            if (!value) {
+                const usagePositionals = positionals.map(posArg => `<${posArg.name}>`).join(' ');
+                throw new Error(`Missing required positional argument, i.e.: "${command.name} ${usagePositionals}"`);
+            }
+            result[pos.name] = value;
+        }
+    }
+    // Handle options
+    // Start parsing options after all non-option args used for positionals
+    argIndex = 0;
+    const consumedArgs = new Set();
+    // Mark all nonOptionArgs indices as consumed for positionals
+    let tempNonOptionIndex = 0;
+    for (let i = 0; i < positionals.length; i++) {
+        const pos = positionals[i];
+        if (pos.variadic) {
+            const remaining = positionals.length - (i + 1);
+            const values = nonOptionArgs.slice(tempNonOptionIndex, nonOptionArgs.length - remaining);
+            for (let j = tempNonOptionIndex; j < tempNonOptionIndex + values.length; j++) {
+                consumedArgs.add(args.findIndex((a, idx) => !a.startsWith('-') && !consumedArgs.has(idx) && a === nonOptionArgs[j]));
+            }
+            tempNonOptionIndex += values.length;
+        }
+        else {
+            const value = nonOptionArgs[tempNonOptionIndex++];
+            consumedArgs.add(args.findIndex((a, idx) => !a.startsWith('-') && !consumedArgs.has(idx) && a === value));
+        }
+    }
+    while (argIndex < args.length) {
+        if (consumedArgs.has(argIndex)) {
+            argIndex++;
+            continue;
+        }
+        const argOrg = args[argIndex] || '';
+        let arg = args[argIndex];
+        let option;
+        let configKey;
+        if (argOrg.startsWith('-')) {
+            if (argOrg.startsWith('--')) {
+                arg = argOrg.slice(2);
+                // Try all forms: as-is, kebab-to-camel, camel-to-kebab
+                option = options[arg] || options[kebabToCamel(arg)] || options[camelToKebab(arg).replace(/-/g, '')];
+                if (option) {
+                    // Find the actual config key
+                    for (const key of Object.keys(options)) {
+                        if (options[key] === option) {
+                            configKey = key;
+                            break;
+                        }
+                    }
+                }
+                if (!option) {
+                    // Try matching aliases in all forms
+                    for (const key of Object.keys(options)) {
+                        const opt = options[key];
+                        if (!opt.alias)
+                            continue;
+                        if (opt.alias.includes(arg) || opt.alias.includes(kebabToCamel(arg)) || opt.alias.includes(camelToKebab(arg))) {
+                            option = opt;
+                            configKey = key;
+                            break;
+                        }
+                    }
+                }
+            }
+            else if (argOrg.startsWith('-')) {
+                // alias
+                arg = argOrg.slice(1);
+                if (arg) {
+                    const optionKeys = Object.keys(options);
+                    for (let j = 0; j < optionKeys.length; j++) {
+                        const opt = options[optionKeys[j]];
+                        if (!opt.alias)
+                            continue;
+                        if (opt.alias === arg || opt.alias === kebabToCamel(arg) || opt.alias === camelToKebab(arg)) {
+                            option = opt;
+                            configKey = optionKeys[j];
+                            break;
+                        }
+                    }
+                }
+            }
+            if (!option) {
+                // Handle negated boolean in both forms
+                const isNegated = arg.startsWith('no-');
+                const optionName = isNegated ? arg.slice(3) : arg;
+                const camelOptionName = kebabToCamel(optionName);
+                option = options[optionName] || options[camelOptionName];
+                configKey = camelOptionName in options ? camelOptionName : optionName;
+                if (option?.type === 'boolean') {
+                    if (result[optionName] !== undefined || result[camelOptionName] !== undefined) {
+                        throw new Error('Providing same negated and truthy argument are not allowed');
+                    }
+                    result[configKey] = !isNegated;
+                    argIndex++;
+                    continue;
+                }
+            }
+            if (!option || !configKey) {
+                throw new Error(`Unknown option: ${arg}`);
+            }
+            switch (option.type || 'string') {
+                case 'boolean':
+                    if (result[configKey] !== undefined) {
+                        throw new Error('Providing same negated and truthy argument are not allowed');
+                    }
+                    result[configKey] = !argOrg.startsWith('--no-') && !argOrg.startsWith('-no-');
+                    break;
+                case 'string':
+                    if (args[argIndex + 1] === undefined || args[argIndex + 1].startsWith('-')) {
+                        throw new Error(`Missing value for option: ${configKey}`);
+                    }
+                    result[configKey] = args[++argIndex];
+                    break;
+                case 'number':
+                    if (args[argIndex + 1] === undefined || args[argIndex + 1].startsWith('-')) {
+                        throw new Error(`Missing value for option: ${configKey}`);
+                    }
+                    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}`);
+                    }
+                    result[configKey].push(arrayValue);
+                    break;
+                }
+            }
+        }
+        else {
+            throw new Error(`Unknown argument: ${arg}`);
+        }
+        argIndex++;
+    }
+    // After all parsing, check for required options
+    Object.entries(options).forEach(([key, opt]) => {
+        if (opt.required && result[key] === undefined) {
+            const aliasStr = opt.alias ? `-${opt.alias}, ` : '';
+            throw new Error(`Missing required option: ${aliasStr}--${key}`);
+        }
+    });
+    return result;
+}
+function printHelp(config) {
+    const { command, options } = config;
+    // Build usage string for positionals
+    const usagePositionals = (command.positional ?? [])
+        .map(p => {
+        const variadic = p.variadic ? '..' : '';
+        if (p.required) {
+            return `<${p.name}${variadic}>`;
+        }
+        return `[${p.name}${variadic}]`;
+    })
+        .join(' ');
+    console.log('Usage:');
+    console.log(`  ${command.name} ${usagePositionals} [options]  ${command.description}`);
+    console.log('\nPositionals:');
+    command.positional?.forEach(arg => {
+        console.log(`  ${arg.name.padEnd(20)}${arg.description.slice(0, 65).padEnd(65)}[${arg.type || 'string'}]`);
+    });
+    console.log('\nOptions:');
+    Object.keys(options).forEach(key => {
+        const option = options[key];
+        const requiredStr = option.required ? '[required]' : '';
+        const aliasStr = option.alias ? `-${option.alias}, ` : '';
+        console.log(`  ${aliasStr.padEnd(4)}--${key.padEnd(14)}${(option.description || '').slice(0, 65).padEnd(65)}[${option.type || 'string'}]${requiredStr}`);
+    });
+    console.log('\nDefault options:');
+    console.log(`${padString('  -h, --help', 21)} ${padString('Show help', 64)} [boolean]`);
+    console.log(`${padString('  -v, --version', 21)} ${padString('Show version number', 64)} [boolean]`);
+    console.log('\n');
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

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

package/dist/interfaces.d.ts

@@ -0,0 +1,33 @@
+export interface ArgumentOptions {
+    /** command option type */
+    type?: 'string' | 'boolean' | 'number' | 'array';
+    /** description of the command option */
+    description: string;
+    /** defaults to undefined, provide shorter aliases as command options */
+    alias?: string | string[];
+    /** defaults to false, is the option required? */
+    required?: boolean;
+}
+export interface CommandOptions {
+    /** CLI command name, used in the help docs */
+    name: string;
+    description: string;
+    positional?: {
+        /** positional argument name (it will be displayed in the help docs) */
+        name: string;
+        /** positional argument description */
+        description: string;
+        /** postional argument type */
+        type?: 'string';
+        /** defaults to false, allows multiple values for this positional argument */
+        variadic?: boolean;
+        /** defaults to false, is the positional argument required? */
+        required?: boolean;
+    }[];
+}
+export interface Config {
+    command: CommandOptions;
+    options: Record<string, ArgumentOptions>;
+    version: string;
+}
+//# sourceMappingURL=interfaces.d.ts.map

package/dist/interfaces.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"interfaces.d.ts","sourceRoot":"","sources":["../src/interfaces.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,eAAe;IAC9B,0BAA0B;IAC1B,IAAI,CAAC,EAAE,QAAQ,GAAG,SAAS,GAAG,QAAQ,GAAG,OAAO,CAAC;IACjD,wCAAwC;IACxC,WAAW,EAAE,MAAM,CAAC;IACpB,wEAAwE;IACxE,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IAC1B,iDAAiD;IACjD,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED,MAAM,WAAW,cAAc;IAC7B,8CAA8C;IAC9C,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE;QACX,uEAAuE;QACvE,IAAI,EAAE,MAAM,CAAC;QACb,sCAAsC;QACtC,WAAW,EAAE,MAAM,CAAC;QACpB,8BAA8B;QAC9B,IAAI,CAAC,EAAE,QAAQ,CAAC;QAChB,6EAA6E;QAC7E,QAAQ,CAAC,EAAE,OAAO,CAAC;QACnB,8DAA8D;QAC9D,QAAQ,CAAC,EAAE,OAAO,CAAC;KACpB,EAAE,CAAC;CACL;AAED,MAAM,WAAW,MAAM;IACrB,OAAO,EAAE,cAAc,CAAC;IACxB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC;IACzC,OAAO,EAAE,MAAM,CAAC;CACjB"}

package/dist/interfaces.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=interfaces.js.map

package/dist/interfaces.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"interfaces.js","sourceRoot":"","sources":["../src/interfaces.ts"],"names":[],"mappings":""}

package/dist/utils.d.ts

@@ -0,0 +1,7 @@
+/** Utility to convert kebab-case to camelCase */
+export declare function kebabToCamel(str: string): string;
+/** Utility to convert camelCase to kebab-case */
+export declare function camelToKebab(str: string): string;
+/** add whitespace padding to any input string */
+export declare function padString(input: string, padding: number): string;
+//# sourceMappingURL=utils.d.ts.map

package/dist/utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../src/utils.ts"],"names":[],"mappings":"AAAA,iDAAiD;AACjD,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,UAEvC;AAED,iDAAiD;AACjD,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,UAEvC;AAED,iDAAiD;AACjD,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,UAEvD"}

package/dist/utils.js

@@ -0,0 +1,13 @@
+/** Utility to convert kebab-case to camelCase */
+export function kebabToCamel(str) {
+    return str.replace(/-([a-z])/g, (_, c) => c.toUpperCase());
+}
+/** Utility to convert camelCase to kebab-case */
+export function camelToKebab(str) {
+    return str.replace(/([a-z0-9])([A-Z])/g, '$1-$2').toLowerCase();
+}
+/** add whitespace padding to any input string */
+export function padString(input, padding) {
+    return input.padEnd(padding);
+}
+//# sourceMappingURL=utils.js.map

package/dist/utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.js","sourceRoot":"","sources":["../src/utils.ts"],"names":[],"mappings":"AAAA,iDAAiD;AACjD,MAAM,UAAU,YAAY,CAAC,GAAW;IACtC,OAAO,GAAG,CAAC,OAAO,CAAC,WAAW,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC,CAAC;AAC7D,CAAC;AAED,iDAAiD;AACjD,MAAM,UAAU,YAAY,CAAC,GAAW;IACtC,OAAO,GAAG,CAAC,OAAO,CAAC,oBAAoB,EAAE,OAAO,CAAC,CAAC,WAAW,EAAE,CAAC;AAClE,CAAC;AAED,iDAAiD;AACjD,MAAM,UAAU,SAAS,CAAC,KAAa,EAAE,OAAe;IACtD,OAAO,KAAK,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;AAC/B,CAAC"}

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "cli-nano",
+  "version": "0.2.0",
+  "description": "Mini command-line tool similar to `yargs` or `parseArgs` from Node.js that accepts positional arguments, flags and options.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "types": "./dist/index.d.ts",
+  "module": "./dist/index.js",
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "/dist",
+    "/src"
+  ],
+  "license": "MIT",
+  "author": "Ghislain B.",
+  "homepage": "https://github.com/ghiscoding/cli-nano",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ghiscoding/cli-nano.git"
+  },
+  "bugs": {
+    "url": "https://github.com/ghiscoding/cli-nano/issues"
+  },
+  "scripts": {
+    "clean": "premove dist",
+    "build": "npm run clean && npm run biome:write && tsc",
+    "biome:check": "npm run biome:lint:check && npm run biome:format:check",
+    "biome:write": "npm run biome:lint:write && npm run biome:format:write",
+    "biome:lint:check": "biome lint ./src",
+    "biome:lint:write": "biome lint --write ./src",
+    "biome:format:check": "biome format ./src",
+    "biome:format:write": "biome format --write ./src",
+    "preview:release": "release-it --only-version --dry-run",
+    "release": "release-it --only-version",
+    "test": "vitest --watch --config ./vitest.config.mts",
+    "test:coverage": "vitest --coverage --config ./vitest.config.mts"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.0.5",
+    "@release-it/conventional-changelog": "^10.0.1",
+    "@types/node": "^22.15.33",
+    "@vitest/coverage-v8": "^3.2.4",
+    "premove": "^4.0.0",
+    "release-it": "^19.0.3",
+    "typescript": "^5.8.3",
+    "vitest": "^3.2.4"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  }
+}

package/src/__tests__/parse-args.spec.ts

@@ -0,0 +1,502 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+import { parseArgs } from '../index.js';
+import type { Config } from '../interfaces.js';
+
+const config: Config = {
+  command: {
+    name: 'copyfiles',
+    description: 'Copy files from a source to a destination directory',
+    positional: [
+      {
+        name: 'inFile',
+        description: 'source files',
+        type: 'string',
+        required: true,
+      },
+      {
+        name: 'outDirectory',
+        description: 'destination directory',
+        required: true,
+      },
+    ],
+  },
+  options: {
+    all: {
+      alias: 'a',
+      type: 'boolean',
+      description: 'include files & directories begining with a dot (.)',
+    },
+    dryRun: {
+      alias: 'd',
+      type: 'boolean',
+      description: 'Show what would be copied, but do not actually copy any files',
+    },
+    exclude: {
+      alias: 'e',
+      type: 'array',
+      description: 'pattern or glob to exclude (may be passed multiple times)',
+    },
+    up: {
+      type: 'number',
+      description: 'slice a path off the bottom of the paths',
+    },
+    bar: {
+      alias: 'b',
+      required: true,
+      description: 'a required bar option',
+    },
+  },
+  version: '0.1.6',
+};
+
+describe('parseArgs', () => {
+  beforeEach(() => {
+    vi.spyOn(process, 'argv', 'get').mockReturnValue(['node', 'cli.js', ...[]]);
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it('should parse positional arguments correctly', () => {
+    const args = ['file1.txt', 'output/', '--bar', 'value'];
+    vi.spyOn(process, 'argv', 'get').mockReturnValue(['node', 'cli.js', ...args]);
+
+    const result = parseArgs(config);
+
+    expect(result.inFile).toBe('file1.txt');
+    expect(result.outDirectory).toBe('output/');
+  });
+
+  it('should parse camelCase boolean options correctly', () => {
+    const args = ['file1.txt', 'output/', '--all', '--no-dryRun', '--bar', 'value'];
+    vi.spyOn(process, 'argv', 'get').mockReturnValue(['node', 'cli.js', ...args]);
+
+    const result = parseArgs(config);
+
+    expect(result.inFile).toBe('file1.txt');
+    expect(result.outDirectory).toBe('output/');
+    expect(result.all).toBe(true);
+    expect(result.dryRun).toBe(false);
+  });
+
+  it('should parse kebab-case boolean options correctly', () => {
+    const args = ['file1.txt', 'output/', '--all', '--no-dry-run', '--bar', 'value'];
+    vi.spyOn(process, 'argv', 'get').mockReturnValue(['node', 'cli.js', ...args]);
+
+    const result = parseArgs(config);
+
+    expect(result.inFile).toBe('file1.txt');
+    expect(result.outDirectory).toBe('output/');
+    expect(result.all).toBe(true);
+    expect(result.dryRun).toBe(false);
+  });
+
+  it('should parse string options correctly', () => {
+    const args = ['file1.txt', 'output/', '--up', '2', '--bar', 'value'];
+    vi.spyOn(process, 'argv', 'get').mockReturnValue(['node', 'cli.js', ...args]);
+    const result = parseArgs(config);
+    expect(result.up).toBe(2);
+  });
+
+  it('should parse string options correctly with an alias', () => {
+    const args = ['file1.txt', 'output/', '--up', '2', '-b', 'value'];
+    vi.spyOn(process, 'argv', 'get').mockReturnValue(['node', 'cli.js', ...args]);
+    const result = parseArgs(config);
+    expect(result.up).toBe(2);
+    expect(result.bar).toBe('value');
+  });
+
+  it('should parse array options correctly when defined at the end of the command options', () => {
+    const args = ['file1.txt', 'output/', '-b', 'value', '--exclude', 'pattern1', '--exclude', 'pattern2'];
+    vi.spyOn(process, 'argv', 'get').mockReturnValue(['node', 'cli.js', ...args]);
+    const result = parseArgs(config);
+    expect(result.exclude).toEqual(['pattern1', 'pattern2']);
+    expect(result.bar).toBe('value');
+  });
+
+  it('should parse array options correctly when defined in the middle of the command options with camelCase arguments', () => {
+    const args = ['file1.txt', 'output/', '--exclude', 'pattern1', '--exclude', 'pattern2', '-b', 'value', '--dryRun'];
+    vi.spyOn(process, 'argv', 'get').mockReturnValue(['node', 'cli.js', ...args]);
+    const result = parseArgs(config);
+    expect(result.exclude).toEqual(['pattern1', 'pattern2']);
+    expect(result.dryRun).toBe(true);
+    expect(result.bar).toBe('value');
+  });
+
+  it('should parse array options correctly when defined in the middle of the command options with kebab-case arguments', () => {
+    const args = ['file1.txt', 'output/', '--exclude', 'pattern1', '--exclude', 'pattern2', '-b', 'value', '--dry-run'];
+    vi.spyOn(process, 'argv', 'get').mockReturnValue(['node', 'cli.js', ...args]);
+    const result = parseArgs(config);
+    expect(result.exclude).toEqual(['pattern1', 'pattern2']);
+    expect(result.dryRun).toBe(true);
+    expect(result.bar).toBe('value');
+  });
+
+  it('should throw an error for unknown options', () => {
+    const args = ['file1.txt', 'output/', '-b', 'value', '--unknown'];
+    vi.spyOn(process, 'argv', 'get').mockReturnValue(['node', 'cli.js', ...args]);
+    expect(() => parseArgs(config)).toThrowError('Unknown option: unknown');
+  });
+
+  it('should throw an error for unknown kebab-case options', () => {
+    const args = ['file1.txt', 'output/', '-b', 'value', '--unknown-kebab'];
+    vi.spyOn(process, 'argv', 'get').mockReturnValue(['node', 'cli.js', ...args]);
+    expect(() => parseArgs(config)).toThrowError('Unknown option: unknown-kebab');
+  });
+
+  it('should throw an error for unknown camelCase options', () => {
+    const args = ['file1.txt', 'output/', '-b', 'value', '--unknownCamel'];
+    vi.spyOn(process, 'argv', 'get').mockReturnValue(['node', 'cli.js', ...args]);
+    expect(() => parseArgs(config)).toThrowError('Unknown option: unknownCamel');
+  });
+
+  it('should throw when truthy and --no camelCase prefix arguments are both provided', () => {
+    const args = ['file1.txt', 'output/', '--all', '--dryRun', '--no-dryRun', '-b', 'value'];
+    vi.spyOn(process, 'argv', 'get').mockReturnValue(['node', 'cli.js', ...args]);
+    expect(() => parseArgs(config)).toThrowError('Providing same negated and truthy argument are not allowed');
+  });
+
+  it('should throw when truthy and --no kebab-case prefix arguments are both provided', () => {
+    const args = ['file1.txt', 'output/', '--all', '--dryRun', '--no-dry-run', '-b', 'value'];
+    vi.spyOn(process, 'argv', 'get').mockReturnValue(['node', 'cli.js', ...args]);
+    expect(() => parseArgs(config)).toThrowError('Providing same negated and truthy argument are not allowed');
+  });
+
+  it('should throw when --no prefix and truthy arguments are both provided', () => {
+    const args = ['file1.txt', 'output/', '--all', '--no-dryRun', '--dryRun', '-b', 'value'];
+    vi.spyOn(process, 'argv', 'get').mockReturnValue(['node', 'cli.js', ...args]);
+    expect(() => parseArgs(config)).toThrowError('Providing same negated and truthy argument are not allowed');
+  });
+
+  it('should throw when positional arguments are missing', () => {
+    const args = ['file1.txt', '--all', '--dryRun'];
+    vi.spyOn(process, 'argv', 'get').mockReturnValue(['node', 'cli.js', ...args]);
+
+    expect(() => parseArgs(config)).toThrow('Missing required positional argument, i.e.: "copyfiles <inFile> <outDirectory>');
+  });
+
+  it('should throw when positional arguments are missing and it will not try to read "value" as positional argument either', () => {
+    const args = ['file1.txt', '--all', '--dryRun', '-b', 'value'];
+    vi.spyOn(process, 'argv', 'get').mockReturnValue(['node', 'cli.js', ...args]);
+
+    expect(() => parseArgs(config)).toThrow('Missing required positional argument, i.e.: "copyfiles <inFile> <outDirectory>');
+  });
+
+  it('should throw when required options are missing', () => {
+    const args = ['file1.txt', 'output', '--all', '--dryRun'];
+    vi.spyOn(process, 'argv', 'get').mockReturnValue(['node', 'cli.js', ...args]);
+
+    expect(() => parseArgs(config)).toThrow('Missing required option: -b, --bar');
+  });
+
+  it('should throw if the same alias is defined for multiple options', () => {
+    const configWithDupAlias: Config = {
+      ...config,
+      options: {
+        foo: { alias: 'x', type: 'boolean', description: '' },
+        bar: { alias: 'x', type: 'boolean', description: '' },
+      },
+    };
+    expect(() => parseArgs(configWithDupAlias)).toThrow('Duplicate alias detected: "x" used for both "foo" and "bar"');
+  });
+
+  it('should handle help command', () =>
+    new Promise((done: any) => {
+      const consoleLogSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
+      const args = ['--help'];
+      vi.spyOn(process, 'argv', 'get').mockReturnValue(['node', 'cli.js', ...args]);
+      try {
+        parseArgs(config);
+      } catch (error: any) {
+        expect(error.message).toBe('process.exit unexpectedly called with "0"');
+        expect(consoleLogSpy).toHaveBeenCalledWith(expect.stringContaining('Usage:'));
+        expect(consoleLogSpy).toHaveBeenCalledWith(
+          expect.stringContaining('copyfiles <inFile> <outDirectory> [options]  Copy files from a source to a destination directory'),
+        );
+        expect(consoleLogSpy).toHaveBeenCalledWith(expect.stringContaining('\nPositionals:'));
+        expect(consoleLogSpy).toHaveBeenCalledWith(
+          expect.stringContaining('  inFile              source files                                                     [string]'),
+        );
+        expect(consoleLogSpy).toHaveBeenCalledWith(
+          expect.stringContaining('  -d, --dryRun        Show what would be copied, but do not actually copy any files    [boolean]'),
+        );
+        expect(consoleLogSpy).toHaveBeenCalledWith(
+          expect.stringContaining(
+            '  -b, --bar           a required bar option                                            [string][required]',
+          ),
+        );
+        expect(consoleLogSpy).toHaveBeenCalledWith(expect.stringContaining('\nDefault options:'));
+        expect(consoleLogSpy).toHaveBeenCalledWith(
+          expect.stringContaining('  -h, --help          Show help                                                        [boolean]'),
+        );
+        expect(consoleLogSpy).toHaveBeenCalledWith(
+          expect.stringContaining('  -v, --version       Show version number                                              [boolean]'),
+        );
+        done();
+      }
+    }));
+
+  it('should handle version command', () =>
+    new Promise((done: any) => {
+      const consoleLogSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
+      const args = ['--version'];
+      vi.spyOn(process, 'argv', 'get').mockReturnValue(['node', 'cli.js', ...args]);
+      try {
+        parseArgs(config);
+      } catch (error: any) {
+        expect(error.message).toBe('process.exit unexpectedly called with "0"');
+        expect(consoleLogSpy).toHaveBeenCalledWith(expect.stringContaining('0.1.6'));
+        done();
+      }
+    }));
+
+  it('should parse optional variadic positional arguments (zero or more)', () => {
+    const config: Config = {
+      command: {
+        name: 'test',
+        description: 'Test optional variadic',
+        positional: [
+          {
+            name: 'inputs',
+            description: 'input files',
+            type: 'string',
+            variadic: true,
+            required: false,
+          },
+          {
+            name: 'outDir',
+            description: 'output directory',
+            required: true,
+          },
+        ],
+      },
+      options: {},
+      version: '1.0.0',
+    };
+    // No inputs
+    let args = ['dist'];
+    vi.spyOn(process, 'argv', 'get').mockReturnValue(['node', 'cli.js', ...args]);
+    let result = parseArgs(config);
+    expect(result.inputs).toEqual([]);
+    expect(result.outDir).toBe('dist');
+
+    // Multiple inputs
+    args = ['file1', 'file2', 'dist'];
+    vi.spyOn(process, 'argv', 'get').mockReturnValue(['node', 'cli.js', ...args]);
+    result = parseArgs(config);
+    expect(result.inputs).toEqual(['file1', 'file2']);
+    expect(result.outDir).toBe('dist');
+  });
+
+  it('should parse a single optional variadic positional arguments (zero or more)', () => {
+    const config: Config = {
+      command: {
+        name: 'test',
+        description: 'Test optional variadic',
+        positional: [
+          {
+            name: 'inputs',
+            description: 'input files',
+            type: 'string',
+            variadic: true,
+            required: true,
+          },
+        ],
+      },
+      options: {},
+      version: '1.0.0',
+    };
+    // No inputs
+    let args: string[] = [];
+    vi.spyOn(process, 'argv', 'get').mockReturnValue(['node', 'cli.js', ...args]);
+    expect(() => parseArgs(config)).toThrow('Missing required positional argument, i.e.: "test <inputs>');
+
+    // Multiple inputs
+    args = ['file1', 'file2'];
+    vi.spyOn(process, 'argv', 'get').mockReturnValue(['node', 'cli.js', ...args]);
+    const result = parseArgs(config);
+    expect(result.inputs).toEqual(['file1', 'file2']);
+  });
+
+  it('should print usage with required variadic positional argument using <inFile..>', () => {
+    const configWithVariadic: Config = {
+      ...config,
+      command: {
+        ...config.command,
+        positional: [
+          {
+            name: 'inFile',
+            description: 'source files',
+            type: 'string',
+            variadic: true,
+            required: true,
+          },
+          {
+            name: 'outDirectory',
+            description: 'destination directory',
+            required: true,
+          },
+        ],
+      },
+    };
+    const spy = vi.spyOn(console, 'log').mockImplementation(() => {});
+    vi.spyOn(process, 'argv', 'get').mockReturnValue(['node', 'cli.js', '--help']);
+    try {
+      parseArgs(configWithVariadic);
+    } catch {}
+    expect(spy).toHaveBeenCalledWith(expect.stringContaining('<inFile..>'));
+    spy.mockRestore();
+  });
+
+  it('should print usage without any positional argument defined', () => {
+    const configWithoutPositional: Config = {
+      ...config,
+      command: {
+        ...config.command,
+      },
+      options: {
+        file: {
+          description: 'source files',
+          type: 'string',
+        },
+      },
+    };
+    const spy = vi.spyOn(console, 'log').mockImplementation(() => {});
+    vi.spyOn(process, 'argv', 'get').mockReturnValue(['node', 'cli.js', '--help']);
+    try {
+      parseArgs(configWithoutPositional);
+    } catch {}
+    expect(spy).toHaveBeenCalledWith(expect.stringContaining('--file'));
+    expect(spy).toHaveBeenCalledWith(expect.stringContaining('source files'));
+    expect(spy).toHaveBeenCalledWith(expect.stringContaining('[string]'));
+    spy.mockRestore();
+  });
+
+  it('should throw if required boolean flag is missing', () => {
+    const config: Config = {
+      command: {
+        name: 'test',
+        description: 'Test required flag',
+      },
+      options: {
+        force: {
+          alias: 'f',
+          type: 'boolean',
+          required: true,
+          description: 'Force operation',
+        },
+      },
+      version: '1.0.0',
+    };
+    const args: string[] = [];
+    vi.spyOn(process, 'argv', 'get').mockReturnValue(['node', 'cli.js', ...args]);
+    expect(() => parseArgs(config)).toThrow('Missing required option: -f, --force');
+  });
+
+  it('should parse kebab-case long option when alias is camelCase', () => {
+    const configWithCamelAlias: Config = {
+      ...config,
+      options: {
+        ...config.options,
+        testOption: {
+          alias: 'testAliasCamel',
+          type: 'boolean',
+          description: 'A test option with camelCase alias',
+        },
+      },
+    };
+    const args = ['file1.txt', 'output/', '--test-alias-camel', '-b', 'value'];
+    vi.spyOn(process, 'argv', 'get').mockReturnValue(['node', 'cli.js', ...args]);
+    const result = parseArgs(configWithCamelAlias);
+    expect(result.testOption).toBe(true);
+  });
+
+  it('should parse camelCase long option when alias is kebab-case', () => {
+    const configWithKebabAlias: Config = {
+      ...config,
+      options: {
+        ...config.options,
+        testOption: {
+          alias: 'test-alias-kebab',
+          type: 'boolean',
+          description: 'A test option with kebab-case alias',
+        },
+      },
+    };
+    const args = ['file1.txt', 'output/', '--testAliasKebab', '-b', 'value'];
+    vi.spyOn(process, 'argv', 'get').mockReturnValue(['node', 'cli.js', ...args]);
+    const result = parseArgs(configWithKebabAlias);
+    expect(result.testOption).toBe(true);
+  });
+
+  it('should throw if too many positional arguments are provided', () => {
+    const args = ['file1.txt', 'output/', 'extra.txt', '-b', 'value'];
+    vi.spyOn(process, 'argv', 'get').mockReturnValue(['node', 'cli.js', ...args]);
+    expect(() => parseArgs(config)).toThrow('Unknown argument: extra.txt');
+  });
+
+  it('should throw if array option is missing a value', () => {
+    const args = ['file1.txt', 'output/', '--exclude', '-b', 'value'];
+    vi.spyOn(process, 'argv', 'get').mockReturnValue(['node', 'cli.js', ...args]);
+    expect(() => parseArgs(config)).toThrow('Missing value for array option: exclude');
+  });
+
+  it('should throw if string option is missing a value', () => {
+    const args = ['file1.txt', 'output/', '--bar'];
+    vi.spyOn(process, 'argv', 'get').mockReturnValue(['node', 'cli.js', ...args]);
+    expect(() => parseArgs(config)).toThrow('Missing value for option: bar');
+  });
+
+  it('should throw if number option is missing a value', () => {
+    const args = ['file1.txt', 'output/', '--up'];
+    vi.spyOn(process, 'argv', 'get').mockReturnValue(['node', 'cli.js', ...args]);
+    expect(() => parseArgs(config)).toThrow('Missing value for option: up');
+  });
+
+  it('should throw unknown option when short flag does not match any alias', () => {
+    const configWithNoAlias: Config = {
+      ...config,
+      options: {
+        ...config.options,
+        noAliasOpt: {
+          type: 'boolean',
+          description: 'Option with no alias',
+        },
+      },
+    };
+    const args = ['file1.txt', 'output/', '-x', '-b', 'value'];
+    vi.spyOn(process, 'argv', 'get').mockReturnValue(['node', 'cli.js', ...args]);
+    expect(() => parseArgs(configWithNoAlias)).toThrow('Unknown option: x');
+  });
+
+  it('should print usage with optional positional argument', () => {
+    const configWithOptional: Config = {
+      ...config,
+      command: {
+        ...config.command,
+        positional: [
+          {
+            name: 'inFile',
+            description: 'source files',
+            type: 'string',
+            required: false, // <-- optional positional
+          },
+          {
+            name: 'outDirectory',
+            description: 'destination directory',
+            required: true,
+          },
+        ],
+      },
+    };
+    const spy = vi.spyOn(console, 'log').mockImplementation(() => {});
+    vi.spyOn(process, 'argv', 'get').mockReturnValue(['node', 'cli.js', '--help']);
+    try {
+      parseArgs(configWithOptional);
+    } catch {}
+    expect(spy).toHaveBeenCalledWith(expect.stringContaining('[inFile]'));
+    spy.mockRestore();
+  });
+});

package/src/index.ts

@@ -0,0 +1,235 @@
+import type { ArgumentOptions, Config } from './interfaces.js';
+import { camelToKebab, kebabToCamel, padString } from './utils.js';
+
+export function parseArgs(config: Config): Record<string, any> {
+  const { command, options, version } = config;
+  const args = process.argv.slice(2);
+  const result: Record<string, any> = {};
+
+  // Check for duplicate aliases
+  const aliasMap = new Map<string, string>();
+  for (const [key, opt] of Object.entries(options)) {
+    if (opt.alias) {
+      const optAlias = opt.alias as string;
+      if (aliasMap.has(optAlias)) {
+        throw new Error(`Duplicate alias detected: "${opt.alias}" used for both "${aliasMap.get(optAlias)}" and "${key}"`);
+      }
+      aliasMap.set(optAlias, key);
+    }
+  }
+
+  // Handle --help and --version before anything else
+  if (args.includes('--help') || args.includes('-h')) {
+    printHelp(config);
+    process.exit(0);
+  }
+  if (args.includes('--version') || args.includes('-v')) {
+    console.log(version);
+    process.exit(0);
+  }
+
+  // Handle positional arguments
+  let argIndex = 0;
+  const positionals = command.positional ?? [];
+  const nonOptionArgs: string[] = [];
+  while (argIndex < args.length && !args[argIndex].startsWith('-')) {
+    nonOptionArgs.push(args[argIndex]);
+    argIndex++;
+  }
+  let nonOptionIndex = 0;
+
+  for (let i = 0; i < positionals.length; i++) {
+    const pos = positionals[i];
+    if (pos.variadic) {
+      const remaining = positionals.length - (i + 1);
+      const values = nonOptionArgs.slice(nonOptionIndex, nonOptionArgs.length - remaining);
+      if (pos.required && values.length === 0) {
+        const usagePositionals = positionals.map(posArg => `<${posArg.name}>`).join(' ');
+        throw new Error(`Missing required positional argument, i.e.: "${command.name} ${usagePositionals}"`);
+      }
+      result[pos.name] = values;
+      nonOptionIndex += values.length;
+    } else {
+      const value = nonOptionArgs[nonOptionIndex++];
+      if (!value) {
+        const usagePositionals = positionals.map(posArg => `<${posArg.name}>`).join(' ');
+        throw new Error(`Missing required positional argument, i.e.: "${command.name} ${usagePositionals}"`);
+      }
+      result[pos.name] = value;
+    }
+  }
+
+  // Handle options
+  // Start parsing options after all non-option args used for positionals
+  argIndex = 0;
+  const consumedArgs = new Set<number>();
+  // Mark all nonOptionArgs indices as consumed for positionals
+  let tempNonOptionIndex = 0;
+  for (let i = 0; i < positionals.length; i++) {
+    const pos = positionals[i];
+    if (pos.variadic) {
+      const remaining = positionals.length - (i + 1);
+      const values = nonOptionArgs.slice(tempNonOptionIndex, nonOptionArgs.length - remaining);
+      for (let j = tempNonOptionIndex; j < tempNonOptionIndex + values.length; j++) {
+        consumedArgs.add(args.findIndex((a, idx) => !a.startsWith('-') && !consumedArgs.has(idx) && a === nonOptionArgs[j]));
+      }
+      tempNonOptionIndex += values.length;
+    } else {
+      const value = nonOptionArgs[tempNonOptionIndex++];
+      consumedArgs.add(args.findIndex((a, idx) => !a.startsWith('-') && !consumedArgs.has(idx) && a === value));
+    }
+  }
+
+  while (argIndex < args.length) {
+    if (consumedArgs.has(argIndex)) {
+      argIndex++;
+      continue;
+    }
+    const argOrg = args[argIndex] || '';
+    let arg = args[argIndex];
+    let option: ArgumentOptions | undefined;
+    let configKey: string | undefined;
+
+    if (argOrg.startsWith('-')) {
+      if (argOrg.startsWith('--')) {
+        arg = argOrg.slice(2);
+        // Try all forms: as-is, kebab-to-camel, camel-to-kebab
+        option = options[arg] || options[kebabToCamel(arg)] || options[camelToKebab(arg).replace(/-/g, '')];
+        if (option) {
+          // Find the actual config key
+          for (const key of Object.keys(options)) {
+            if (options[key] === option) {
+              configKey = key;
+              break;
+            }
+          }
+        }
+        if (!option) {
+          // Try matching aliases in all forms
+          for (const key of Object.keys(options)) {
+            const opt = options[key];
+            if (!opt.alias) continue;
+            if (opt.alias.includes(arg) || opt.alias.includes(kebabToCamel(arg)) || opt.alias.includes(camelToKebab(arg))) {
+              option = opt;
+              configKey = key;
+              break;
+            }
+          }
+        }
+      } else if (argOrg.startsWith('-')) {
+        // alias
+        arg = argOrg.slice(1);
+        if (arg) {
+          const optionKeys = Object.keys(options);
+          for (let j = 0; j < optionKeys.length; j++) {
+            const opt = options[optionKeys[j]];
+            if (!opt.alias) continue;
+            if (opt.alias === arg || opt.alias === kebabToCamel(arg) || opt.alias === camelToKebab(arg)) {
+              option = opt;
+              configKey = optionKeys[j];
+              break;
+            }
+          }
+        }
+      }
+
+      if (!option) {
+        // Handle negated boolean in both forms
+        const isNegated = arg.startsWith('no-');
+        const optionName = isNegated ? arg.slice(3) : arg;
+        const camelOptionName = kebabToCamel(optionName);
+        option = options[optionName] || options[camelOptionName];
+        configKey = camelOptionName in options ? camelOptionName : optionName;
+        if (option?.type === 'boolean') {
+          if (result[optionName] !== undefined || result[camelOptionName] !== undefined) {
+            throw new Error('Providing same negated and truthy argument are not allowed');
+          }
+          result[configKey] = !isNegated;
+          argIndex++;
+          continue;
+        }
+      }
+
+      if (!option || !configKey) {
+        throw new Error(`Unknown option: ${arg}`);
+      }
+
+      switch (option.type || 'string') {
+        case 'boolean':
+          if (result[configKey] !== undefined) {
+            throw new Error('Providing same negated and truthy argument are not allowed');
+          }
+          result[configKey] = !argOrg.startsWith('--no-') && !argOrg.startsWith('-no-');
+          break;
+        case 'string':
+          if (args[argIndex + 1] === undefined || args[argIndex + 1].startsWith('-')) {
+            throw new Error(`Missing value for option: ${configKey}`);
+          }
+          result[configKey] = args[++argIndex];
+          break;
+        case 'number':
+          if (args[argIndex + 1] === undefined || args[argIndex + 1].startsWith('-')) {
+            throw new Error(`Missing value for option: ${configKey}`);
+          }
+          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}`);
+          }
+          result[configKey].push(arrayValue);
+          break;
+        }
+      }
+    } else {
+      throw new Error(`Unknown argument: ${arg}`);
+    }
+    argIndex++;
+  }
+
+  // After all parsing, check for required options
+  Object.entries(options).forEach(([key, opt]) => {
+    if (opt.required && result[key] === undefined) {
+      const aliasStr = opt.alias ? `-${opt.alias}, ` : '';
+      throw new Error(`Missing required option: ${aliasStr}--${key}`);
+    }
+  });
+
+  return result;
+}
+
+function printHelp(config: Config) {
+  const { command, options } = config;
+
+  // Build usage string for positionals
+  const usagePositionals = (command.positional ?? [])
+    .map(p => {
+      const variadic = p.variadic ? '..' : '';
+      if (p.required) {
+        return `<${p.name}${variadic}>`;
+      }
+      return `[${p.name}${variadic}]`;
+    })
+    .join(' ');
+  console.log('Usage:');
+  console.log(`  ${command.name} ${usagePositionals} [options]  ${command.description}`);
+  console.log('\nPositionals:');
+  command.positional?.forEach(arg => {
+    console.log(`  ${arg.name.padEnd(20)}${arg.description.slice(0, 65).padEnd(65)}[${arg.type || 'string'}]`);
+  });
+  console.log('\nOptions:');
+  Object.keys(options).forEach(key => {
+    const option = options[key];
+    const requiredStr = option.required ? '[required]' : '';
+    const aliasStr = option.alias ? `-${option.alias}, ` : '';
+    console.log(
+      `  ${aliasStr.padEnd(4)}--${key.padEnd(14)}${(option.description || '').slice(0, 65).padEnd(65)}[${option.type || 'string'}]${requiredStr}`,
+    );
+  });
+  console.log('\nDefault options:');
+  console.log(`${padString('  -h, --help', 21)} ${padString('Show help', 64)} [boolean]`);
+  console.log(`${padString('  -v, --version', 21)} ${padString('Show version number', 64)} [boolean]`);
+  console.log('\n');
+}

package/src/interfaces.ts

@@ -0,0 +1,34 @@
+export interface ArgumentOptions {
+  /** command option type */
+  type?: 'string' | 'boolean' | 'number' | 'array';
+  /** description of the command option */
+  description: string;
+  /** defaults to undefined, provide shorter aliases as command options */
+  alias?: string | string[];
+  /** defaults to false, is the option required? */
+  required?: boolean;
+}
+
+export interface CommandOptions {
+  /** CLI command name, used in the help docs */
+  name: string;
+  description: string;
+  positional?: {
+    /** positional argument name (it will be displayed in the help docs) */
+    name: string;
+    /** positional argument description */
+    description: string;
+    /** postional argument type */
+    type?: 'string';
+    /** defaults to false, allows multiple values for this positional argument */
+    variadic?: boolean;
+    /** defaults to false, is the positional argument required? */
+    required?: boolean;
+  }[];
+}
+
+export interface Config {
+  command: CommandOptions;
+  options: Record<string, ArgumentOptions>;
+  version: string;
+}

package/src/utils.ts

@@ -0,0 +1,14 @@
+/** Utility to convert kebab-case to camelCase */
+export function kebabToCamel(str: string) {
+  return str.replace(/-([a-z])/g, (_, c) => c.toUpperCase());
+}
+
+/** Utility to convert camelCase to kebab-case */
+export function camelToKebab(str: string) {
+  return str.replace(/([a-z0-9])([A-Z])/g, '$1-$2').toLowerCase();
+}
+
+/** add whitespace padding to any input string */
+export function padString(input: string, padding: number) {
+  return input.padEnd(padding);
+}