@ls-stack/cli 0.1.0

package/dist/main.d.mts

@@ -0,0 +1,409 @@
+//#region src/cliInput.d.ts
+/**
+ * Validation function for text inputs.
+ *
+ * @param value - The current input value to validate
+ * @returns `true` if valid, `false` if invalid, or a string error message
+ *
+ * @example
+ * ```ts
+ * const validate: ValidateFn = (value) => {
+ *   if (value.length < 3) return 'Must be at least 3 characters';
+ *   return true;
+ * };
+ * ```
+ */
+type ValidateFn = (value: string) => boolean | string | Promise<boolean | string>;
+/**
+ * Option configuration for select and autocomplete prompts.
+ *
+ * @template T - The string literal type for the option value
+ *
+ * @example
+ * ```ts
+ * const options: SelectOption<'dev' | 'prod'>[] = [
+ *   { value: 'dev', label: 'Development', hint: 'Local environment' },
+ *   { value: 'prod', label: 'Production' },
+ * ];
+ * ```
+ */
+type SelectOption<T extends string> = {
+  /** The value returned when this option is selected */value: T; /** Display text shown to the user (defaults to value if not provided) */
+  label?: string; /** Additional description or help text for the option */
+  hint?: string;
+};
+/**
+ * Interactive CLI input utilities with ESC-to-cancel support.
+ *
+ * All prompts exit the process with code 0 when the user presses ESC or Ctrl+C.
+ *
+ * @example
+ * ```ts
+ * import { cliInput } from '@ls-stack/cli';
+ *
+ * const name = await cliInput.text('Enter your name');
+ * const confirm = await cliInput.confirm('Proceed?', { initial: true });
+ * ```
+ */
+declare const cliInput: {
+  /**
+   * Single selection prompt from a list of options.
+   *
+   * @template T - String literal union type of option values
+   * @param title - The prompt message displayed to the user
+   * @param options - Configuration object containing the selectable options
+   * @returns The value of the selected option
+   *
+   * @example
+   * ```ts
+   * const env = await cliInput.select('Select environment', {
+   *   options: [
+   *     { value: 'dev', label: 'Development', hint: 'Local server' },
+   *     { value: 'prod', label: 'Production' },
+   *   ],
+   * });
+   * // env: 'dev' | 'prod'
+   * ```
+   */
+  select: <T extends string>(title: string, {
+    options
+  }: {
+    options: SelectOption<T>[];
+  }) => Promise<T>;
+  /**
+   * Text input with autocomplete suggestions.
+   *
+   * Searches across option values, labels, and hints (case-insensitive).
+   * Allows free-form text input with optional validation.
+   *
+   * @template T - String literal union type of option values
+   * @param title - The prompt message displayed to the user
+   * @param options - Configuration with autocomplete options and optional validation
+   * @returns The selected or entered value
+   *
+   * @example
+   * ```ts
+   * const framework = await cliInput.textWithAutocomplete('Select framework', {
+   *   options: [
+   *     { value: 'react', label: 'React', hint: 'UI library' },
+   *     { value: 'vue', label: 'Vue', hint: 'Progressive framework' },
+   *   ],
+   *   validate: (v) => v.length > 0 || 'Required',
+   * });
+   * ```
+   */
+  textWithAutocomplete: <T extends string>(title: string, {
+    options,
+    validate
+  }: {
+    options: SelectOption<T>[];
+    validate?: ValidateFn;
+  }) => Promise<T>;
+  /**
+   * Text input prompt with optional default value and validation.
+   *
+   * @param title - The prompt message displayed to the user
+   * @param options - Configuration with optional initial value and validation
+   * @returns The entered text
+   *
+   * @example
+   * ```ts
+   * const name = await cliInput.text('Project name', {
+   *   initial: 'my-project',
+   *   validate: (v) => /^[a-z0-9-]+$/.test(v) || 'Invalid name',
+   * });
+   * ```
+   */
+  text: (title: string, {
+    initial,
+    validate
+  }?: {
+    initial?: string;
+    validate?: ValidateFn;
+  }) => Promise<string>;
+  /**
+   * Yes/No confirmation prompt.
+   *
+   * @param title - The prompt message displayed to the user
+   * @param options - Configuration with optional default value
+   * @returns `true` for yes, `false` for no
+   *
+   * @example
+   * ```ts
+   * const proceed = await cliInput.confirm('Deploy to production?', {
+   *   initial: false,
+   * });
+   * ```
+   */
+  confirm: (title: string, {
+    initial
+  }?: {
+    initial?: boolean;
+  }) => Promise<boolean>;
+  /**
+   * Multi-select prompt with checkboxes.
+   *
+   * Requires at least one option to be selected.
+   *
+   * @template T - String literal union type of option values
+   * @param title - The prompt message displayed to the user
+   * @param options - Configuration object containing the selectable options
+   * @returns Array of selected option values
+   *
+   * @example
+   * ```ts
+   * const features = await cliInput.multipleSelect('Enable features', {
+   *   options: [
+   *     { value: 'typescript', label: 'TypeScript' },
+   *     { value: 'eslint', label: 'ESLint' },
+   *     { value: 'prettier', label: 'Prettier' },
+   *   ],
+   * });
+   * // features: ('typescript' | 'eslint' | 'prettier')[]
+   * ```
+   */
+  multipleSelect: <T extends string>(title: string, {
+    options
+  }: {
+    options: SelectOption<T>[];
+  }) => Promise<T[]>;
+  /**
+   * Numeric input prompt.
+   *
+   * Returns `null` on non-cancellation errors (cancellation exits the process).
+   *
+   * @param title - The prompt message displayed to the user
+   * @param options - Configuration with optional default value
+   * @returns The entered number, or `null` on error
+   *
+   * @example
+   * ```ts
+   * const port = await cliInput.number('Enter port', { initial: 3000 });
+   * if (port !== null) {
+   *   console.log(`Using port ${port}`);
+   * }
+   * ```
+   */
+  number: (title: string, {
+    initial
+  }?: {
+    initial?: number;
+  }) => Promise<number | null>;
+};
+//#endregion
+//#region src/createCli.d.ts
+/**
+ * Positional argument definition for CLI commands.
+ *
+ * Positional arguments are parsed in the order they are defined in the `args` object.
+ *
+ * @example
+ * ```ts
+ * // String positional arg (required)
+ * { type: 'positional-string', name: 'filename', description: 'File to process' }
+ *
+ * // Number positional arg with default (optional)
+ * { type: 'positional-number', name: 'port', description: 'Port number', default: 3000 }
+ * ```
+ */
+type PositionalArg = {
+  type: 'positional-string';
+  name: string;
+  default?: string;
+  description: string;
+} | {
+  type: 'positional-number';
+  name: string;
+  default?: number;
+  description: string;
+};
+/**
+ * Argument definition for CLI commands.
+ *
+ * Supports positional arguments, boolean flags, and value flags.
+ *
+ * **Argument Types:**
+ * - `positional-string` - Required string argument (optional if `default` is provided)
+ * - `positional-number` - Required number argument (optional if `default` is provided)
+ * - `flag` - Boolean flag (`--verbose`), defaults to `false`
+ * - `value-string-flag` - Flag with string value (`--config file.json`)
+ * - `value-number-flag` - Flag with number value (`--port 8080`)
+ *
+ * @example
+ * ```ts
+ * const args = {
+ *   name: { type: 'positional-string', name: 'name', description: 'Project name' },
+ *   port: { type: 'value-number-flag', name: 'port', description: 'Port', default: 3000 },
+ *   verbose: { type: 'flag', name: 'verbose', description: 'Verbose output' },
+ * };
+ * ```
+ */
+type Arg = PositionalArg | {
+  type: 'flag';
+  name: string;
+  description: string;
+} | {
+  type: 'value-string-flag';
+  default?: string;
+  name: string;
+  description: string;
+} | {
+  type: 'value-number-flag';
+  default?: number;
+  name: string;
+  description: string;
+};
+type Cmd = {
+  short?: string;
+  description: string;
+  run: (...args: any[]) => Promise<void> | void;
+  args?: Record<string, Arg>;
+  examples?: {
+    args: string[];
+    description: string;
+  }[];
+};
+type GetArgType<T extends Arg> = T extends PositionalArg ? T['type'] extends 'positional-string' ? T['default'] extends string ? string : string | undefined : T['type'] extends 'positional-number' ? T['default'] extends number ? number : number | undefined : never : T extends {
+  type: 'flag';
+} ? boolean : T extends {
+  type: 'value-string-flag';
+} ? T['default'] extends string ? string : string | undefined : T extends {
+  type: 'value-number-flag';
+} ? T['default'] extends number ? number : number | undefined : never;
+/**
+ * Creates a type-safe command definition for use with `createCLI`.
+ *
+ * The `run` function receives fully typed arguments based on the `args` definition.
+ * Positional arguments are parsed in declaration order.
+ *
+ * @template Args - Record of argument definitions
+ * @param options - Command configuration
+ * @param options.description - Command description shown in help
+ * @param options.short - Optional single-character alias (cannot be 'i' or 'h')
+ * @param options.args - Typed argument definitions
+ * @param options.run - Handler function receiving parsed arguments
+ * @param options.examples - Optional usage examples for help text
+ * @returns Command definition object
+ *
+ * @example
+ * ```ts
+ * const deploy = createCmd({
+ *   short: 'd',
+ *   description: 'Deploy the application',
+ *   args: {
+ *     env: {
+ *       type: 'positional-string',
+ *       name: 'env',
+ *       description: 'Target environment',
+ *     },
+ *     port: {
+ *       type: 'value-number-flag',
+ *       name: 'port',
+ *       description: 'Port number',
+ *       default: 3000,
+ *     },
+ *     verbose: {
+ *       type: 'flag',
+ *       name: 'verbose',
+ *       description: 'Enable verbose logging',
+ *     },
+ *   },
+ *   examples: [
+ *     { args: ['production'], description: 'Deploy to production' },
+ *     { args: ['staging', '--port', '8080'], description: 'Deploy to staging on port 8080' },
+ *   ],
+ *   run: async ({ env, port, verbose }) => {
+ *     // env: string, port: number, verbose: boolean
+ *     console.log(`Deploying to ${env} on port ${port}`);
+ *   },
+ * });
+ * ```
+ */
+declare function createCmd<Args extends undefined | Record<string, Arg>>({
+  short,
+  description,
+  run,
+  args,
+  examples
+}: {
+  short?: string;
+  description: string;
+  args?: Args;
+  run: (cmdArgs: { [K in keyof Args]: Args[K] extends Arg ? GetArgType<Args[K]> : never }) => Promise<void> | void;
+  examples?: {
+    args: string[];
+    description: string;
+  }[];
+}): {
+  short: string | undefined;
+  description: string;
+  run: (cmdArgs: { [K in keyof Args]: Args[K] extends Arg ? GetArgType<Args[K]> : never }) => Promise<void> | void;
+  args: Args | undefined;
+  examples: {
+    args: string[];
+    description: string;
+  }[] | undefined;
+};
+/**
+ * Creates and runs a CLI application with the given commands.
+ *
+ * Automatically handles argument parsing, help generation, and interactive mode.
+ *
+ * **Built-in commands:**
+ * - `h` or `--help` - Shows help with all commands
+ * - `i` - Interactive mode (select command from list)
+ * - `<command> -h` - Shows help for a specific command
+ *
+ * @template C - String literal union of command names
+ * @param options - CLI configuration
+ * @param options.name - CLI display name shown in header
+ * @param options.baseCmd - Command prefix for help text (e.g., 'my-cli')
+ * @param options.sort - Optional array to customize command display order
+ * @param cmds - Record of command definitions created with `createCmd`
+ *
+ * @example
+ * ```ts
+ * await createCLI(
+ *   { name: 'My CLI', baseCmd: 'my-cli' },
+ *   {
+ *     hello: createCmd({
+ *       short: 'hi',
+ *       description: 'Say hello',
+ *       run: async () => console.log('Hello!'),
+ *     }),
+ *     deploy: createCmd({
+ *       short: 'd',
+ *       description: 'Deploy the app',
+ *       args: {
+ *         env: { type: 'positional-string', name: 'env', description: 'Environment' },
+ *       },
+ *       run: async ({ env }) => console.log(`Deploying to ${env}`),
+ *     }),
+ *   },
+ * );
+ * ```
+ *
+ * @example
+ * ```bash
+ * # Usage examples:
+ * my-cli              # Show interactive menu
+ * my-cli h            # Show help
+ * my-cli i            # Interactive mode
+ * my-cli hello        # Run hello command
+ * my-cli hi           # Run hello via short alias
+ * my-cli deploy prod  # Run deploy with argument
+ * my-cli deploy -h    # Show deploy command help
+ * ```
+ */
+declare function createCLI<C extends string>({
+  name,
+  sort,
+  baseCmd
+}: {
+  name: string;
+  sort?: NoInfer<C>[];
+  baseCmd: string;
+}, cmds: Record<C, Cmd>): Promise<void>;
+//#endregion
+export { type Arg, type PositionalArg, type SelectOption, type ValidateFn, cliInput, createCLI, createCmd };
+//# sourceMappingURL=main.d.mts.map