cli-api 0.1.1 → 0.2.0

package/README.md

@@ -5,36 +5,33 @@ Easily create a CLI app.
 ## Usage
 
 ```ts
-import run from "cli-api";
+import {App, Command} from 'cli-api'
 import * as pkg from '../package.json'
-import commands from './commands'
 
-run({
-    name: "hello",
-    version: pkg.version,
-    argv0: pkg.name,
-    commands: [
-        {
-            name: "world",
-            alias: 'w',
-            description: 'Prints "Hello World".',
-            async execute(opts, args) {
-                console.log(`Hello ${opts.name}`)
-            },
-            options: [
-                {
-                    name: 'name',
-                    alias: 'n',
-                    description: "Person you want to greet",
-                    required: true,
-                },
-            ]
+const world = new Command('world')
+    .describe('Prints a greeting.')
+    .flag('verbose', {
+        alias: 'v',
+        description: 'Print more info',
+    })
+    .arg('name', {
+        description: 'Person you want to greet',
+        required: true,
+    })
+    .run((args, kwargs) => {
+        if (kwargs.verbose) {
+            console.log('Preparing greeting...')
         }
-    ]
-})
+        console.log(`Hello ${kwargs.name}`)
+    })
+
+await new App('hello')
+    .meta({version: pkg.version, argv0: pkg.name})
+    .command(world)
+    .execute()
 ```
 
 ```shell
-$ hello world -n Mark
+$ hello world Mark
 Hello Mark
 ```

package/dist/index.d.mts

@@ -0,0 +1,394 @@
+import { ChalkInstance, ColorSupportLevel } from "chalk";
+
+//#region src/color.d.ts
+type ColorMode = 'always' | 'auto' | 'never';
+//#endregion
+//#region src/interfaces.d.ts
+type U2I<U> = (U extends any ? (k: U) => void : never) extends ((k: infer I) => void) ? I : never;
+type OptionalKeys<T> = { [K in keyof T]-?: {} extends Pick<T, K> ? K : never }[keyof T];
+type RequiredKeys<T> = Exclude<keyof T, OptionalKeys<T>>;
+type Flatten<T> = { [K in keyof T]: T[K] } & {};
+type Simplify<T> = { [K in RequiredKeys<T>]: T[K] } & { [K in OptionalKeys<T>]?: Exclude<T[K], undefined> };
+type PrimitiveOfOptType<T extends AnyOptType | undefined> = T extends undefined ? string : T extends OptType.STRING ? string : T extends OptType.BOOL ? boolean : T extends OptType.INT | OptType.FLOAT ? number : T extends OptType.INPUT_FILE | OptType.INPUT_DIRECTORY | OptType.OUTPUT_FILE | OptType.OUTPUT_DIRECTORY | OptType.EMPTY_DIRECTORY ? string : T extends readonly (infer L)[] ? (L extends string ? L : string) : string;
+type KeyOfItem<I> = I extends {
+  key: infer K extends string;
+} ? K : I extends {
+  name: infer N extends string;
+} ? N : never;
+type TypeOfItem<I> = I extends {
+  type: infer T extends AnyOptType;
+} ? T : undefined;
+type IsRepeatable<I> = I extends {
+  repeatable: true | number;
+} ? true : false;
+type IsRequired<I> = I extends {
+  required: true | number;
+} ? true : false;
+type IsAlwaysPresent<I> = IsRepeatable<I> extends true ? true : IsRequired<I>;
+type ValueOfOption<O extends Option> = IsRepeatable<O> extends true ? PrimitiveOfOptType<TypeOfItem<O>>[] : PrimitiveOfOptType<TypeOfItem<O>>;
+type OptionPropMap<I extends Option> = { [K in KeyOfItem<I>]: ValueOfOption<I> };
+type FlagPropMap<F extends Flag> = { [K in KeyOfItem<F>]: boolean };
+type MergeOptionProps<IU extends Option> = U2I<IU extends any ? OptionPropMap<IU> : never>;
+type MergeFlagProps<FU extends Flag> = U2I<FU extends any ? FlagPropMap<FU> : never>;
+type RequiredOptions<I extends Option> = I extends any ? (IsAlwaysPresent<I> extends true ? I : never) : never;
+type OptionalOptions<I extends Option> = Exclude<I, RequiredOptions<I>>;
+type OptionsOf<Opts extends readonly Option[] | undefined, Flags extends readonly Flag[] | undefined> = (Opts extends readonly any[] ? (MergeOptionProps<RequiredOptions<Opts[number]>> & Partial<MergeOptionProps<OptionalOptions<Opts[number]>>>) : {}) & (Flags extends readonly any[] ? Partial<MergeFlagProps<Flags[number]>> : {});
+type ValueOfArg<A$1 extends Argument> = IsRepeatable<A$1> extends true ? PrimitiveOfOptType<TypeOfItem<A$1>>[] : PrimitiveOfOptType<TypeOfItem<A$1>>;
+type _ArgsFixed<As extends readonly Argument[], Acc extends unknown[] = []> = As extends readonly [infer A, ...infer R] ? A extends Argument ? IsRepeatable<A> extends true ? Acc : _ArgsFixed<R & readonly Argument[], [...Acc, ValueOfArg<A>]> : Acc : Acc;
+type _ArgsTailRepeat<As extends readonly Argument[]> = As extends readonly [...infer _, infer L] ? L extends Argument ? (IsRepeatable<L> extends true ? PrimitiveOfOptType<TypeOfItem<L>> : never) : never : never;
+type ArgumentPropMap<I extends Argument> = { [K in KeyOfItem<I>]: ValueOfArg<I> };
+type MergeArgumentProps<IU extends Argument> = U2I<IU extends any ? ArgumentPropMap<IU> : never>;
+type RequiredArguments<I extends Argument> = I extends any ? (IsAlwaysPresent<I> extends true ? I : never) : never;
+type OptionalArguments<I extends Argument> = Exclude<I, RequiredArguments<I>>;
+type ArgsOf<As extends readonly Argument[] | undefined> = As extends readonly Argument[] ? _ArgsTailRepeat<As> extends never ? _ArgsFixed<As> : [..._ArgsFixed<As>, ..._ArgsTailRepeat<As>[]] : unknown[];
+type OptsOf<Opts extends readonly Option[] | undefined, Flags extends readonly Flag[] | undefined, As extends readonly Argument[] | undefined> = Simplify<OptionsOf<Opts, Flags> & (As extends readonly any[] ? (MergeArgumentProps<RequiredArguments<As[number]>> & Partial<MergeArgumentProps<OptionalArguments<As[number]>>>) : {})>;
+type MaybePromise<V> = V | PromiseLike<V>;
+declare enum OptType {
+  STRING = 0,
+  BOOL = 1,
+  INT = 2,
+  FLOAT = 3,
+  /** A string, truncated and converted to lowercase. */
+  ENUM = 4,
+  /** File must be readable. Single dash will be converted to STDIN. */
+  INPUT_FILE = 5,
+  /** Directory must be readable. */
+  INPUT_DIRECTORY = 6,
+  /** File's directory must exist and be writeable. Single dash will be converted to STDOUT. */
+  OUTPUT_FILE = 7,
+  OUTPUT_DIRECTORY = 8,
+  /** An empty or non-existent directory. */
+  EMPTY_DIRECTORY = 9,
+}
+interface ArgumentOrOptionOrFlag {
+  /** Name of the option to display in help. */
+  name: string;
+  /** Alternative name for this option. */
+  alias?: string | string[];
+  /** Description of the option. */
+  description?: string;
+  /** Default value to display in help. */
+  defaultValueText?: string;
+  /** Property name to use in `run()` opts. */
+  key?: string;
+}
+type AnyOptType = OptType | readonly string[];
+interface ArgumentOrOption extends ArgumentOrOptionOrFlag {
+  /** Type to coerce the option value to. */
+  type?: AnyOptType;
+  /** Allowed values for `OptType.ENUM`. */
+  enumValues?: readonly string[];
+  /** Option or positional may be provided more than once. When set to a number, that number is the maximum count. */
+  repeatable?: boolean | number;
+  /** Option or positional is required. For repeatable positionals, a number means the minimum count required. */
+  required?: boolean | number;
+  /** Default value if not provided. */
+  defaultValue?: any | (() => any);
+}
+/** Same as options, but the type is bool and a value is not required. */
+interface Flag extends ArgumentOrOptionOrFlag, OptionOrFlag {
+  valueNotRequired?: true;
+  /** Default value if not provided. */
+  defaultValue?: boolean | (() => boolean);
+}
+/** Positional argument. */
+interface Argument extends ArgumentOrOption {}
+interface OptionOrFlag {
+  /** Add a `--no-${name}` long-form alias that uses `valueIfNoPrefix` or `false`. */
+  noPrefix?: boolean;
+  /** Value to use when the option is present without an explicit value. */
+  valueIfSet?: any | (() => any);
+  /** Value to use when the `--no-${name}` form is provided. */
+  valueIfNoPrefix?: any | (() => any);
+}
+/** Option with value. */
+interface Option extends ArgumentOrOption, OptionOrFlag {
+  /** Placeholder value to use in help. */
+  valuePlaceholder?: string;
+  /** Caller may specify a value (`--opt=value`), but it's not required. When omitted, `valueIfSet` is used. */
+  valueNotRequired?: boolean;
+}
+type CommandBase = {
+  name: string;
+  alias?: string | string[];
+  description?: string;
+  longDescription?: string;
+};
+type AnyApp = App<any, any, any, any, any>;
+type LeafCommand<Opts extends readonly Option[] | undefined = undefined, Flags extends readonly Flag[] | undefined = undefined, As extends readonly Argument[] | undefined = undefined> = LeafCommandInput<Opts, Flags, As>;
+type BranchCommand<Cs extends CommandChildren = CommandChildren> = BranchCommandInput<Cs>;
+type CommandShape<Opts extends readonly Option[] | undefined = undefined, Flags extends readonly Flag[] | undefined = undefined, As extends readonly Argument[] | undefined = undefined, Cs extends CommandChildren = CommandChildren> = LeafCommand<Opts, Flags, As> | BranchCommand<Cs>;
+type CommandChildren = readonly CommandShape<any, any, any, any>[];
+interface ExecutableInput<Opts extends readonly Option[] | undefined, Flags extends readonly Flag[] | undefined, As extends readonly Argument[] | undefined> {
+  options?: Opts;
+  flags?: Flags;
+  positonals?: As;
+  execute(opts: OptsOf<Opts, Flags, As>, args: ArgsOf<As>, context: ExecutionContext): MaybePromise<number | void>;
+}
+interface LeafCommandInput<Opts extends readonly Option[] | undefined, Flags extends readonly Flag[] | undefined, As extends readonly Argument[] | undefined> extends CommandBase, ExecutableInput<Opts, Flags, As> {
+  subCommands?: never;
+}
+interface BranchCommandInput<Cs extends CommandChildren> extends CommandBase {
+  subCommands: Cs;
+  options?: never;
+  flags?: never;
+  positonals?: never;
+  execute?: never;
+}
+/**
+ * Per-invocation execution state exposed to command handlers.
+ */
+declare class ExecutionContext {
+  private readonly _app;
+  private readonly _commandPath;
+  private readonly _chalk;
+  /**
+   * Creates a context for a single CLI invocation.
+   *
+   * @param app The root app being executed.
+   * @param colorMode The resolved color mode for the current invocation.
+   * @param path The resolved command path for the current invocation.
+   */
+  constructor(app: AnyApp, colorMode?: ColorMode, path?: readonly string[]);
+  /**
+   * Gets the root app for the current invocation.
+   *
+   * @returns The app definition being executed.
+   */
+  get app(): AnyApp;
+  /**
+   * Gets the resolved command path for the current invocation.
+   *
+   * @returns The command names from the app root to the executing command.
+   */
+  get commandPath(): readonly string[];
+  /**
+   * Gets the chalk instance configured for the current invocation.
+   *
+   * @returns The active chalk instance after built-in color flags such as `--color` and `--no-color` have been applied.
+   */
+  get chalk(): ChalkInstance;
+  /**
+   * Gets the resolved color support level configured for the current invocation.
+   *
+   * @returns The active color level from `0` to `3`.
+   */
+  get colorLevel(): ColorSupportLevel;
+}
+interface AnyLeafCommand extends CommandBase {
+  options?: readonly Option[] | undefined;
+  flags?: readonly Flag[] | undefined;
+  positonals?: readonly Argument[] | undefined;
+  execute(opts: Record<string, any>, args: any[], context: ExecutionContext): MaybePromise<number | void>;
+  subCommands?: never | undefined;
+}
+interface AnyBranchCommand extends CommandBase {
+  subCommands: readonly AnyCmd[];
+  options?: never | undefined;
+  flags?: never | undefined;
+  positonals?: never | undefined;
+  execute?: never | undefined;
+}
+type AnyCmd = AnyLeafCommand | AnyBranchCommand;
+type FlagConfigInput = Omit<Flag, 'name' | 'valueNotRequired'>;
+type OptionConfigInput = Omit<Option, 'name'>;
+type ArgumentConfigInput = Omit<Argument, 'name'>;
+type BuildFlag<Name extends string, Config extends FlagConfigInput | undefined> = Flatten<{
+  name: Name;
+} & (Config extends undefined ? {} : Config)>;
+type BuildOption<Name extends string, Config extends OptionConfigInput | undefined> = Flatten<{
+  name: Name;
+} & (Config extends undefined ? {} : Config)>;
+type BuildArgument<Name extends string, Config extends ArgumentConfigInput | undefined> = Flatten<{
+  name: Name;
+} & (Config extends undefined ? {} : Config)>;
+type RunHandler<Opts extends readonly Option[] | undefined, Flags extends readonly Flag[] | undefined, As extends readonly Argument[] | undefined> = (args: ArgsOf<As>, opts: OptsOf<Opts, Flags, As>, context: ExecutionContext) => MaybePromise<number | void>;
+type ExecuteHandler<Opts extends readonly Option[] | undefined, Flags extends readonly Flag[] | undefined, As extends readonly Argument[] | undefined> = ExecutableInput<Opts, Flags, As>['execute'];
+type AppMetaConfig = {
+  bin?: string;
+  version?: string;
+  author?: string;
+  description?: string;
+  longDescription?: string;
+};
+declare class Command<Opts extends readonly Option[] = [], Flags extends readonly Flag[] = [], As extends readonly Argument[] = [], Cs extends CommandChildren = [], Executable extends boolean = false> {
+  private readonly _name;
+  private _alias?;
+  private _description?;
+  private _longDescription?;
+  private _options?;
+  private _positonals?;
+  private _subCommands?;
+  protected _handler?: ExecuteHandler<Opts, Flags, As>;
+  constructor(name: string);
+  get name(): string;
+  get alias(): string | string[] | undefined;
+  get description(): string | undefined;
+  get longDescription(): string | undefined;
+  get options(): Option[] | undefined;
+  get positonals(): Argument[] | undefined;
+  get subCommands(): AnyCmd[] | undefined;
+  get handler(): ExecuteHandler<Opts, Flags, As> | undefined;
+  protected setLongDescription(longDescription: string): void;
+  /**
+   * Sets one or more aliases for this command.
+   *
+   * @param aliases Alternative names that should resolve to this command.
+   * @returns The same fluent command builder with the aliases applied.
+   */
+  aliases(...aliases: string[]): this;
+  /**
+   * Sets the short and long descriptions used in generated help output.
+   *
+   * @param description The one-line description shown in summaries.
+   * @param longDescription Additional help text shown in detailed command help.
+   * @returns The same fluent command builder with updated descriptions.
+   */
+  describe(description: string, longDescription?: string): this;
+  /**
+   * Adds a boolean flag to this command.
+   *
+   * @param name The CLI flag name without leading dashes.
+   * @param config Optional metadata such as aliases and descriptions.
+   * @returns A fluent command builder whose inferred option shape includes the new flag.
+   */
+  flag<const Name extends string, const Config extends FlagConfigInput | undefined = undefined>(name: Name, config?: Config): Command<Opts, [...Flags, BuildFlag<Name, Config>], As, Cs, Executable>;
+  /**
+   * Adds an option that accepts a value to this command.
+   *
+   * @param name The CLI option name without leading dashes.
+   * @param config Optional metadata such as aliases, descriptions, and coercion rules.
+   * @returns A fluent command builder whose inferred option shape includes the new option.
+   */
+  opt<const Name extends string, const Config extends OptionConfigInput | undefined = undefined>(name: Name, config?: Config): Command<[...Opts, BuildOption<Name, Config>], Flags, As, Cs, Executable>;
+  /**
+   * Adds a positional argument to this command.
+   *
+   * @param name The positional argument name used in help output and inferred opts.
+   * @param config Optional metadata such as coercion and requiredness.
+   * @returns A fluent command builder whose inferred positional tuple includes the new argument.
+   */
+  arg<const Name extends string, const Config extends ArgumentConfigInput | undefined = undefined>(name: Name, config?: Config): Command<Opts, Flags, [...As, BuildArgument<Name, Config>], Cs, Executable>;
+  /**
+   * Adds a nested sub-command to this command.
+   *
+   * @param subCommand The child command to register.
+   * @returns A fluent command builder that is now treated as a branch command.
+   */
+  command(this: Command<Opts, Flags, As, Cs, false>, subCommand: AnyCmd | Command<any, any, any, any, any>): Command<Opts, Flags, As, CommandChildren, false>;
+  /**
+   * Marks this command as executable and registers the handler invoked after parsing.
+   *
+   * @param handler The function that receives parsed positional arguments, parsed option values, and the current [`ExecutionContext`]{@link ExecutionContext}.
+   * @returns A fluent command builder that is now treated as executable.
+   */
+  run(this: Command<Opts, Flags, As, [], false>, handler: RunHandler<Opts, Flags, As>): Command<Opts, Flags, As, [], true>;
+}
+declare class App<Opts extends readonly Option[] = [], Flags extends readonly Flag[] = [], As extends readonly Argument[] = [], Cs extends CommandChildren = [], Executable extends boolean = false> extends Command<Opts, Flags, As, Cs, Executable> {
+  /** @internal */
+  _bin?: string;
+  /** @internal */
+  _version?: string;
+  /** @internal */
+  _author?: string;
+  /** @internal */
+  _globalOptions?: Option[];
+  /**
+   * Applies metadata to the root app in one call.
+   *
+   * @param config Metadata for the app, including version, author, argv0, and descriptions.
+   * @returns The same fluent app builder with the metadata applied.
+   */
+  meta(config: AppMetaConfig): this;
+  /**
+   * Sets the program name shown in help and generated messages.
+   *
+   * @param binaryName The display name for the CLI binary.
+   * @returns The same fluent app builder with the updated program name.
+   */
+  bin(binaryName: string): this;
+  /**
+   * Sets the application version surfaced by the built-in version command.
+   *
+   * @param version The version string to display.
+   * @returns The same fluent app builder with the version applied.
+   */
+  version(version: string): this;
+  /**
+   * Sets the application author surfaced by root help output.
+   *
+   * @param author The author string to display in app help.
+   * @returns The same fluent app builder with the author applied.
+   */
+  author(author: string): this;
+  /**
+   * Adds one or more aliases for the root command while preserving the `App` builder type.
+   *
+   * @param aliases Alternative names that should resolve to the root app.
+   * @returns The same fluent app builder with the aliases applied.
+   */
+  aliases(...aliases: string[]): this;
+  /**
+   * Sets the short and long descriptions used in generated help output while preserving the `App` builder type.
+   *
+   * @param description The one-line description shown in summaries.
+   * @param longDescription Additional help text shown in detailed help.
+   * @returns The same fluent app builder with updated descriptions.
+   */
+  describe(description: string, longDescription?: string): this;
+  /**
+   * Adds a boolean flag to the root app while preserving the `App` builder type.
+   *
+   * @param name The CLI flag name without leading dashes.
+   * @param config Optional metadata such as aliases and descriptions.
+   * @returns A fluent app builder whose inferred option shape includes the new flag.
+   */
+  flag<const Name extends string, const Config extends FlagConfigInput | undefined = undefined>(name: Name, config?: Config): App<Opts, [...Flags, BuildFlag<Name, Config>], As, Cs, Executable>;
+  /**
+   * Adds a valued option to the root app while preserving the `App` builder type.
+   *
+   * @param name The CLI option name without leading dashes.
+   * @param config Optional metadata such as aliases, descriptions, and coercion rules.
+   * @returns A fluent app builder whose inferred option shape includes the new option.
+   */
+  opt<const Name extends string, const Config extends OptionConfigInput | undefined = undefined>(name: Name, config?: Config): App<[...Opts, BuildOption<Name, Config>], Flags, As, Cs, Executable>;
+  /**
+   * Adds a valued option that is available to the root app and every sub-command.
+   *
+   * @param name The CLI option name without leading dashes.
+   * @param config Optional metadata such as aliases, descriptions, and coercion rules.
+   * @returns A fluent app builder whose global option shape includes the new option.
+   */
+  globalOpt<const Name extends string, const Config extends OptionConfigInput | undefined = undefined>(name: Name, config?: Config): this;
+  /**
+   * Adds a positional argument to the root app while preserving the `App` builder type.
+   *
+   * @param name The positional argument name used in help output and inferred opts.
+   * @param config Optional metadata such as coercion and requiredness.
+   * @returns A fluent app builder whose inferred positional tuple includes the new argument.
+   */
+  arg<const Name extends string, const Config extends ArgumentConfigInput | undefined = undefined>(name: Name, config?: Config): App<Opts, Flags, [...As, BuildArgument<Name, Config>], Cs, Executable>;
+  /**
+   * Adds a nested sub-command to the root app while preserving the `App` builder type.
+   *
+   * @param subCommand The child command to register.
+   * @returns A fluent app builder that is now treated as a branch app.
+   */
+  command(this: App<Opts, Flags, As, Cs, false>, subCommand: AnyCmd | Command<any, any, any, any, any>): App<Opts, Flags, As, CommandChildren, false>;
+  /**
+   * Marks the root app as executable by registering the handler invoked after parsing.
+   *
+   * @param handler The function that receives parsed positional arguments, parsed option values including custom global options, and the current [`ExecutionContext`]{@link ExecutionContext}.
+   * @returns A fluent app builder that is now treated as executable.
+   */
+  run(this: App<Opts, Flags, As, [], false>, handler: RunHandler<Opts, Flags, As>): App<Opts, Flags, As, [], true>;
+  /**
+   * Parses CLI arguments and executes the matching root command or sub-command.
+   *
+   * @param args The raw CLI arguments to parse. Defaults to `process.argv.slice(2)`.
+   * @returns The numeric exit code returned by the resolved command handler, or `0` when the handler does not return one.
+   */
+  execute(args?: string[]): Promise<number>;
+}
+//#endregion
+export { type AnyOptType, App, type ArgsOf, type Argument, Command, ExecutionContext, type Flag, OptType, type Option, type OptionsOf, type OptsOf, type RunHandler };

package/dist/index.mjs

@@ -0,0 +1,3 @@
+import { i as OptType, n as Command, r as ExecutionContext, t as App } from "./interfaces-COq24bNI.mjs";
+
+export { App, Command, ExecutionContext, OptType };