feat(inquirerer): add parseArgv helper and tests

- Add parseArgv() to wrap minimist so developers don't need to import it
- Add succinct tests for CLI utilities (parseArgv, extractFirst, package helpers)
- Update README to use parseArgv instead of importing minimist directly
- Update @inquirerer/utils to re-export parseArgv

Author: pyramation

packages/inquirerer-utils/src/index.ts

@@ -1,12 +1,13 @@
 // Re-export core CLI utilities from inquirerer
 export {
+  parseArgv,
   extractFirst,
   cliExitWithError,
   getPackageJson,
   getPackageVersion,
   getPackageName
 } from 'inquirerer';
-export type { ParsedArgs, CliExitOptions, PackageJson } from 'inquirerer';
+export type { ParsedArgs, ParseArgvOptions, CliExitOptions, PackageJson } from 'inquirerer';
 
 // Update checking (requires appstash, not available in inquirerer)
 export { checkForUpdates, shouldSkipUpdateCheck } from './update-check';

packages/inquirerer/README.md

@@ -1279,13 +1279,12 @@ console.log(`Welcome to ${toolName}!`);
 
 ### Argument Parsing
 
-Extract the first positional argument for command routing:
+Parse command-line arguments and extract subcommands:
 
 ```typescript
-import { extractFirst, ParsedArgs } from 'inquirerer';
-import minimist from 'minimist';
+import { parseArgv, extractFirst } from 'inquirerer';
 
-const argv = minimist(process.argv.slice(2));
+const argv = parseArgv(process.argv);
 const { first, newArgv } = extractFirst(argv);
 
 // Running: mycli generate --output ./dist

packages/inquirerer/__tests__/cli.test.ts

@@ -0,0 +1,46 @@
+import { parseArgv, extractFirst, getPackageJson, getPackageVersion, getPackageName } from '../src';
+
+describe('CLI utilities', () => {
+  describe('parseArgv', () => {
+    it('parses flags and positional args', () => {
+      const argv = parseArgv(['node', 'cli', 'generate', '--config', 'test.json', '-v']);
+      expect(argv._).toEqual(['generate']);
+      expect(argv['config']).toBe('test.json');
+      expect(argv['v']).toBe(true);
+    });
+  });
+
+  describe('extractFirst', () => {
+    it('extracts first positional argument', () => {
+      const { first, newArgv } = extractFirst({ _: ['init', 'myproject'], config: 'test.json' } as any);
+      expect(first).toBe('init');
+      expect(newArgv._).toEqual(['myproject']);
+      expect((newArgv as any).config).toBe('test.json');
+    });
+
+    it('handles empty positional args', () => {
+      const { first, newArgv } = extractFirst({ _: [] });
+      expect(first).toBeUndefined();
+      expect(newArgv._).toEqual([]);
+    });
+  });
+
+  describe('package helpers', () => {
+    it('gets package.json from __dirname', () => {
+      const pkg = getPackageJson(__dirname);
+      expect(pkg.name).toBe('inquirerer');
+      expect(pkg.version).toBeDefined();
+    });
+
+    it('getPackageVersion returns version string', () => {
+      const version = getPackageVersion(__dirname);
+      expect(typeof version).toBe('string');
+      expect(version).toMatch(/^\d+\.\d+\.\d+/);
+    });
+
+    it('getPackageName returns name string', () => {
+      const name = getPackageName(__dirname);
+      expect(name).toBe('inquirerer');
+    });
+  });
+});

packages/inquirerer/src/cli/argv.ts

@@ -1,8 +1,22 @@
-import { ParsedArgs } from 'minimist';
+import minimist, { Opts, ParsedArgs } from 'minimist';
+
+/**
+ * Parse command-line arguments using minimist.
+ * Wrapper around minimist so you don't need to import it directly.
+ *
+ * @example
+ * ```typescript
+ * const argv = parseArgv(process.argv);
+ * console.log(argv.config); // --config value
+ * ```
+ */
+export const parseArgv = (args: string[] = process.argv, opts?: Opts): ParsedArgs => {
+  return minimist(args.slice(2), opts);
+};
 
 /**
  * Extracts the first positional argument from argv and returns it along with the remaining argv.
- * This is useful for command routing in CLI applications where the first argument is a subcommand.
+ * Useful for command routing where the first argument is a subcommand.
  *
  * @example
  * ```typescript
@@ -21,4 +35,4 @@ export const extractFirst = (argv: Partial<ParsedArgs>) => {
   return { first, newArgv };
 };
 
-export type { ParsedArgs } from 'minimist';
+export type { ParsedArgs, Opts as ParseArgvOptions } from 'minimist';

packages/inquirerer/src/cli/index.ts

@@ -1,5 +1,5 @@
-export { extractFirst } from './argv';
-export type { ParsedArgs } from './argv';
+export { parseArgv, extractFirst } from './argv';
+export type { ParsedArgs, ParseArgvOptions } from './argv';
 
 export { cliExitWithError } from './error';
 export type { CliExitOptions } from './error';