feat(inquirerer): add core CLI utilities and re-exports

- Add cli/argv.ts with extractFirst function for command routing
- Add cli/error.ts with cliExitWithError function for error handling
- Re-export ParsedArgs type from minimist
- Re-export findAndRequirePackageJson for convenience

This allows CLI tools to import all common utilities from 'inquirerer'
instead of requiring separate imports from @inquirerer/utils,
find-and-require-package-json, and minimist.

Author: pyramation

packages/inquirerer/src/cli/argv.ts

@@ -0,0 +1,24 @@
+import { ParsedArgs } from 'minimist';
+
+/**
+ * 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.
+ *
+ * @example
+ * ```typescript
+ * const { first: command, newArgv } = extractFirst(argv);
+ * if (command === 'init') {
+ *   await handleInit(newArgv);
+ * }
+ * ```
+ */
+export const extractFirst = (argv: Partial<ParsedArgs>) => {
+  const first = argv._?.[0];
+  const newArgv = {
+    ...argv,
+    _: argv._?.slice(1) ?? []
+  };
+  return { first, newArgv };
+};
+
+export type { ParsedArgs } from 'minimist';

packages/inquirerer/src/cli/error.ts

@@ -0,0 +1,55 @@
+export interface CliExitOptions {
+  context?: Record<string, any>;
+  beforeExit?: () => Promise<void>;
+  logger?: {
+    error: (message: string, ...args: any[]) => void;
+    debug: (message: string, ...args: any[]) => void;
+    warn: (message: string, ...args: any[]) => void;
+  };
+}
+
+/**
+ * Exits the CLI with an error message and optional cleanup.
+ * Supports a beforeExit hook for cleanup operations (e.g., closing database connections).
+ *
+ * @example
+ * ```typescript
+ * await cliExitWithError('Invalid configuration file');
+ *
+ * // With cleanup
+ * await cliExitWithError(error, {
+ *   beforeExit: async () => {
+ *     await db.close();
+ *   }
+ * });
+ * ```
+ */
+export const cliExitWithError = async (
+  error: Error | string,
+  options: CliExitOptions = {}
+): Promise<never> => {
+  const { context, beforeExit, logger = console } = options;
+
+  if (error instanceof Error) {
+    logger.error(`Error: ${error.message}`);
+    if (context) {
+      logger.debug('Context:', context);
+    }
+  } else if (typeof error === 'string') {
+    logger.error(`Error: ${error}`);
+    if (context) {
+      logger.debug('Context:', context);
+    }
+  }
+
+  if (beforeExit) {
+    try {
+      await beforeExit();
+      logger.debug('Cleanup completed');
+    } catch (cleanupError) {
+      logger.warn('Failed to complete cleanup:', cleanupError);
+    }
+  }
+
+  process.exit(1);
+};

packages/inquirerer/src/cli/index.ts

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

packages/inquirerer/src/index.ts

@@ -3,3 +3,9 @@ export * from './prompt';
 export * from './question';
 export * from './resolvers';
 export * from './ui';
+
+// CLI utilities for building command-line applications
+export * from './cli';
+
+// Re-export package.json finder for convenience
+export { findAndRequirePackageJson } from 'find-and-require-package-json';