Merge pull request #57 from constructive-io/devin/1768871428-inquirerer-cli-utils

feat(inquirerer): add core CLI utilities and consolidate @inquirerer/utils

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,14 @@
-// Argv utilities
-export { extractFirst } from './argv';
-export type { ParsedArgs } from './argv';
+// Re-export core CLI utilities from inquirerer
+export {
+  parseArgv,
+  extractFirst,
+  cliExitWithError,
+  getPackageJson,
+  getPackageVersion,
+  getPackageName
+} from 'inquirerer';
+export type { ParsedArgs, ParseArgvOptions, CliExitOptions, PackageJson } from 'inquirerer';
 
-// CLI error handling
-export { cliExitWithError } from './cli-error';
-export type { CliExitOptions } from './cli-error';
-
-// 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/index.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,130 @@ 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
+
+Parse command-line arguments and extract subcommands:
+
+```typescript
+import { parseArgv, extractFirst } from 'inquirerer';
+
+const argv = parseArgv(process.argv);
+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/package-json.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/README.md

@@ -0,0 +1,38 @@
+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.
+ * Useful for command routing 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, Opts as ParseArgvOptions } from 'minimist';

packages/inquirerer/__tests__/cli.test.ts

@@ -11,6 +11,18 @@ export interface CliExitOptions {
 /**
  * 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,

packages/inquirerer/src/cli/argv.ts

@@ -0,0 +1,8 @@
+export { parseArgv, extractFirst } from './argv';
+export type { ParsedArgs, ParseArgvOptions } from './argv';
+
+export { cliExitWithError } from './error';
+export type { CliExitOptions } from './error';
+
+export { getPackageJson, getPackageVersion, getPackageName } from './package';
+export type { PackageJson } from './package';

…ckages/inquirerer-utils/src/cli-error.ts packages/inquirerer/src/cli/error.tspackages/inquirerer-utils/src/cli-error.ts renamed to packages/inquirerer/src/cli/error.ts packages/inquirerer-utils/src/cli-error.ts renamed to packages/inquirerer/src/cli/error.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;
+};