feat(inquirerer): add package helpers and update @inquirerer/utils

- Add getPackageJson, getPackageVersion, getPackageName to inquirerer
- Remove findAndRequirePackageJson re-export (use getPackageJson instead)
- Update README with CLI Utilities documentation
- Update @inquirerer/utils to re-export from inquirerer for backwards compat
- Remove duplicated code from @inquirerer/utils (argv.ts, cli-error.ts, package-json.ts)
- Add legacy aliases (getSelfPackageJson, getSelfVersion, getSelfName) for backwards compat

Author: pyramation

packages/inquirerer-utils/package.json

@@ -29,8 +29,7 @@
   },
   "dependencies": {
     "appstash": "workspace:*",
-    "find-and-require-package-json": "workspace:*",
-    "minimist": "^1.2.8"
+    "inquirerer": "workspace:*"
   },
   "devDependencies": {
     "@types/minimist": "^1.2.5",

packages/inquirerer-utils/src/argv.ts

@@ -1,15 +1,19 @@
-// Argv utilities
-export { extractFirst } from './argv';
-export type { ParsedArgs } from './argv';
+// Re-export core CLI utilities from inquirerer for backwards compatibility
+export {
+  extractFirst,
+  cliExitWithError,
+  getPackageJson,
+  getPackageVersion,
+  getPackageName
+} from 'inquirerer';
+export type { ParsedArgs, CliExitOptions, PackageJson } from 'inquirerer';
 
-// CLI error handling
-export { cliExitWithError } from './cli-error';
-export type { CliExitOptions } from './cli-error';
+// Legacy aliases for backwards compatibility
+export { getPackageJson as getSelfPackageJson } from 'inquirerer';
+export { getPackageVersion as getSelfVersion } from 'inquirerer';
+export { getPackageName as getSelfName } from 'inquirerer';
+export type { PackageJson as PackageJsonInfo } from 'inquirerer';
 
-// Update checking
+// Update checking (requires appstash, not available in inquirerer)
 export { checkForUpdates, shouldSkipUpdateCheck } from './update-check';
 export type { UpdateCheckOptions, UpdateCheckResult } from './update-check';
-
-// Package.json utilities
-export { getSelfPackageJson, getSelfVersion, getSelfName } from './package-json';
-export type { PackageJsonInfo } from './package-json';

packages/inquirerer-utils/src/cli-error.ts

@@ -62,6 +62,10 @@ npm install inquirerer
   - [Custom Resolvers](#custom-resolvers)
   - [Resolver Examples](#resolver-examples)
 - [CLI Helper](#cli-helper)
+- [CLI Utilities](#cli-utilities)
+  - [Package Information](#package-information)
+  - [Argument Parsing](#argument-parsing)
+  - [Error Handling](#error-handling)
 - [UI Components](#ui-components)
   - [Spinner](#spinner)
   - [Progress Bar](#progress-bar)
@@ -1248,6 +1252,131 @@ const cli = new CLI(handler, options);
 await cli.run();
 ```
 
+## CLI Utilities
+
+inquirerer provides a complete set of utilities for building CLI applications, so you can import everything from a single package.
+
+### Package Information
+
+Get information about your CLI's package.json for version display and other metadata:
+
+```typescript
+import { getPackageJson, getPackageVersion, getPackageName } from 'inquirerer';
+
+// Get the full package.json object
+const pkg = getPackageJson(__dirname);
+console.log(`${pkg.name}@${pkg.version}`);
+
+// Or use the convenience helpers
+if (argv.version) {
+  console.log(getPackageVersion(__dirname));
+  process.exit(0);
+}
+
+const toolName = getPackageName(__dirname);
+console.log(`Welcome to ${toolName}!`);
+```
+
+### Argument Parsing
+
+Extract the first positional argument for command routing:
+
+```typescript
+import { extractFirst, ParsedArgs } from 'inquirerer';
+import minimist from 'minimist';
+
+const argv = minimist(process.argv.slice(2));
+const { first, newArgv } = extractFirst(argv);
+
+// Running: mycli generate --output ./dist
+// first = 'generate'
+// newArgv = { output: './dist', _: [] }
+
+switch (first) {
+  case 'generate':
+    await handleGenerate(newArgv);
+    break;
+  case 'init':
+    await handleInit(newArgv);
+    break;
+  default:
+    console.log('Unknown command');
+}
+```
+
+### Error Handling
+
+Exit gracefully with error messages and optional cleanup:
+
+```typescript
+import { cliExitWithError, CliExitOptions } from 'inquirerer';
+
+try {
+  await riskyOperation();
+} catch (error) {
+  await cliExitWithError(error, {
+    context: { operation: 'build', target: 'production' },
+    beforeExit: async () => {
+      await cleanup();
+    },
+    logger: customLogger // optional, defaults to console
+  });
+}
+```
+
+### Complete CLI Example
+
+Here's a complete example using all the CLI utilities:
+
+```typescript
+import { 
+  CLI, 
+  CLIOptions, 
+  Inquirerer,
+  extractFirst, 
+  cliExitWithError, 
+  getPackageVersion,
+  ParsedArgs 
+} from 'inquirerer';
+
+const options: Partial<CLIOptions> = {
+  minimistOpts: {
+    alias: { v: 'version', h: 'help' },
+    boolean: ['help', 'version']
+  }
+};
+
+const handler = async (argv: Partial<ParsedArgs>, prompter: Inquirerer) => {
+  if (argv.version) {
+    console.log(getPackageVersion(__dirname));
+    process.exit(0);
+  }
+
+  const { first, newArgv } = extractFirst(argv);
+
+  try {
+    switch (first) {
+      case 'init':
+        await handleInit(newArgv, prompter);
+        break;
+      case 'build':
+        await handleBuild(newArgv, prompter);
+        break;
+      default:
+        console.log('Usage: mycli <command> [options]');
+        console.log('Commands: init, build');
+    }
+  } catch (error) {
+    await cliExitWithError(error, {
+      context: { command: first }
+    });
+  }
+};
+
+const cli = new CLI(handler, options);
+await cli.run();
+```
+
 ## UI Components
 
 inquirerer includes a set of UI components for building rich terminal interfaces beyond simple prompts. These are useful for showing progress, loading states, and streaming output.

packages/inquirerer-utils/src/index.ts

@@ -3,3 +3,6 @@ export type { ParsedArgs } from './argv';
 
 export { cliExitWithError } from './error';
 export type { CliExitOptions } from './error';
+
+export { getPackageJson, getPackageVersion, getPackageName } from './package';
+export type { PackageJson } from './package';

packages/inquirerer-utils/src/package-json.ts

@@ -0,0 +1,51 @@
+import { findAndRequirePackageJson } from 'find-and-require-package-json';
+
+export interface PackageJson {
+  name: string;
+  version: string;
+  [key: string]: any;
+}
+
+/**
+ * Gets the package.json for the current package by searching up from the given directory.
+ * This is useful for CLIs to get their own package information.
+ *
+ * @example
+ * ```typescript
+ * const pkg = getPackageJson(__dirname);
+ * console.log(`${pkg.name}@${pkg.version}`);
+ * ```
+ */
+export const getPackageJson = (dirname: string): PackageJson => {
+  return findAndRequirePackageJson(dirname);
+};
+
+/**
+ * Gets the version from the package.json for the current package.
+ * Shorthand for `getPackageJson(dirname).version`.
+ *
+ * @example
+ * ```typescript
+ * if (argv.version) {
+ *   console.log(getPackageVersion(__dirname));
+ *   process.exit(0);
+ * }
+ * ```
+ */
+export const getPackageVersion = (dirname: string): string => {
+  return getPackageJson(dirname).version;
+};
+
+/**
+ * Gets the name from the package.json for the current package.
+ * Shorthand for `getPackageJson(dirname).name`.
+ *
+ * @example
+ * ```typescript
+ * const toolName = getPackageName(__dirname);
+ * console.log(`Welcome to ${toolName}!`);
+ * ```
+ */
+export const getPackageName = (dirname: string): string => {
+  return getPackageJson(dirname).name;
+};

packages/inquirerer/README.md

@@ -6,6 +6,3 @@ 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';