cli-api 0.2.0 → 0.2.1

package/README.md

@@ -18,17 +18,20 @@ const world = new Command('world')
         description: 'Person you want to greet',
         required: true,
     })
-    .run((args, kwargs) => {
-        if (kwargs.verbose) {
+    .run(opts => {
+        if (opts.verbose) {
             console.log('Preparing greeting...')
         }
-        console.log(`Hello ${kwargs.name}`)
+        console.log(`Hello ${opts.name}`)
     })
 
-await new App('hello')
-    .meta({version: pkg.version, argv0: pkg.name})
+const app = new App('hello')
+    .meta({version: pkg.version, bin: pkg.name})
     .command(world)
-    .execute()
+
+if(import.meta.main) {
+    await app.execute()
+}
 ```
 
 ```shell

package/dist/index.d.mts

@@ -123,7 +123,7 @@ interface ExecutableInput<Opts extends readonly Option[] | undefined, Flags exte
   options?: Opts;
   flags?: Flags;
   positonals?: As;
-  execute(opts: OptsOf<Opts, Flags, As>, args: ArgsOf<As>, context: ExecutionContext): MaybePromise<number | void>;
+  execute(opts: OptsOf<Opts, Flags, 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;
@@ -179,7 +179,7 @@ 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>;
+  execute(opts: Record<string, any>, context: ExecutionContext): MaybePromise<number | void>;
   subCommands?: never | undefined;
 }
 interface AnyBranchCommand extends CommandBase {
@@ -202,7 +202,7 @@ type BuildOption<Name extends string, Config extends OptionConfigInput | undefin
 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 RunHandler<Opts extends readonly Option[] | undefined, Flags extends readonly Flag[] | undefined, As extends readonly Argument[] | undefined> = (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;
@@ -211,6 +211,24 @@ type AppMetaConfig = {
   description?: string;
   longDescription?: string;
 };
+interface BuiltinEntryConfig {
+  /** Override the built-in command and option name. */
+  name?: string;
+  /** Override the built-in command and option aliases. */
+  alias?: string | string[];
+  /** Disable the built-in command entry. */
+  disableCommand?: boolean;
+  /** Disable the built-in global option entry. */
+  disableOption?: boolean;
+}
+interface BuiltinOptionConfig {
+  /** Override the built-in option name. */
+  name?: string;
+  /** Override the built-in option aliases. */
+  alias?: string | string[];
+  /** Disable the built-in global option entry. */
+  disableOption?: boolean;
+}
 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?;
@@ -279,7 +297,7 @@ declare class Command<Opts extends readonly Option[] = [], Flags extends readonl
   /**
    * 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}.
+   * @param handler The function that receives parsed option values, including positional arguments by name, 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>;
@@ -293,6 +311,12 @@ declare class App<Opts extends readonly Option[] = [], Flags extends readonly Fl
   _author?: string;
   /** @internal */
   _globalOptions?: Option[];
+  /** @internal */
+  _helpConfig?: BuiltinEntryConfig;
+  /** @internal */
+  _versionConfig?: BuiltinEntryConfig;
+  /** @internal */
+  _colorConfig?: BuiltinOptionConfig;
   /**
    * Applies metadata to the root app in one call.
    *
@@ -308,12 +332,33 @@ declare class App<Opts extends readonly Option[] = [], Flags extends readonly Fl
    */
   bin(binaryName: string): this;
   /**
-   * Sets the application version surfaced by the built-in version command.
+   * Sets the application version surfaced by the built-in version command and option.
    *
    * @param version The version string to display.
-   * @returns The same fluent app builder with the version applied.
+   * @returns The same fluent app builder with the version text applied.
    */
   version(version: string): this;
+  /**
+   * Configures the built-in version command and global option.
+   *
+   * @param config Built-in version settings such as the displayed name, aliases, and whether the command or option should be disabled.
+   * @returns The same fluent app builder with the version command and option configuration applied.
+   */
+  version(config: BuiltinEntryConfig): this;
+  /**
+   * Configures the built-in help command and global option.
+   *
+   * @param config Built-in help settings such as the displayed name, aliases, and whether the command or option should be disabled.
+   * @returns The same fluent app builder with the help command and option configuration applied.
+   */
+  help(config: BuiltinEntryConfig): this;
+  /**
+   * Configures the built-in color global option.
+   *
+   * @param config Built-in color option settings such as the displayed name, aliases, and whether the option should be disabled.
+   * @returns The same fluent app builder with the color option configuration applied.
+   */
+  color(config: BuiltinOptionConfig): this;
   /**
    * Sets the application author surfaced by root help output.
    *
@@ -378,7 +423,7 @@ declare class App<Opts extends readonly Option[] = [], Flags extends readonly Fl
   /**
    * 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}.
+   * @param handler The function that receives parsed option values including custom global options and positional arguments by name, 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>;

package/dist/index.mjs

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

package/dist/{interfaces-COq24bNI.mjs → interfaces-CfKTHP7y.mjs}

@@ -1,7 +1,93 @@
-import { Chalk, supportsColor } from "chalk";
+import { Chalk } from "chalk";
+import os from "os";
+import process$1 from "process";
 
+//#region src/supports-color.ts
+function hasFlag(flag, argv = globalThis.Deno ? globalThis.Deno.args : process$1.argv) {
+	const prefix = flag.startsWith("-") ? "" : flag.length === 1 ? "-" : "--";
+	const position = argv.indexOf(prefix + flag);
+	const terminatorPosition = argv.indexOf("--");
+	return position !== -1 && (terminatorPosition === -1 || position < terminatorPosition);
+}
+const { env } = process$1;
+let flagForceColor;
+if (hasFlag("no-color") || hasFlag("no-colors") || hasFlag("color=false") || hasFlag("color=never")) flagForceColor = 0;
+else if (hasFlag("color") || hasFlag("colors") || hasFlag("color=true") || hasFlag("color=always")) flagForceColor = 1;
+function envForceColor() {
+	if ("FORCE_COLOR" in env) {
+		const forceColor = env.FORCE_COLOR ?? "";
+		if (forceColor === "true") return 1;
+		if (forceColor === "false") return 0;
+		return forceColor.length === 0 ? 1 : Math.min(Number.parseInt(forceColor, 10), 3);
+	}
+}
+function translateLevel(level) {
+	if (level === 0) return false;
+	return {
+		level,
+		hasBasic: true,
+		has256: level >= 2,
+		has16m: level >= 3
+	};
+}
+function supportsColorInternal(haveStream, { streamIsTTY, sniffFlags = true } = {}) {
+	const noFlagForceColor = envForceColor();
+	if (noFlagForceColor !== void 0) flagForceColor = noFlagForceColor === 0 ? 0 : 1;
+	const forceColor = sniffFlags ? flagForceColor : noFlagForceColor;
+	if (forceColor === 0) return 0;
+	if (sniffFlags) {
+		if (hasFlag("color=16m") || hasFlag("color=full") || hasFlag("color=truecolor")) return 3;
+		if (hasFlag("color=256")) return 2;
+	}
+	if ("TF_BUILD" in env && "AGENT_NAME" in env) return 1;
+	if (haveStream && !streamIsTTY && forceColor === void 0) return 0;
+	const min = forceColor || 0;
+	if ((env.TERM ?? "") === "dumb") return min;
+	if (process$1.platform === "win32") {
+		const osRelease = os.release().split(".");
+		if (Number(osRelease[0]) >= 10 && Number(osRelease[2]) >= 10586) return Number(osRelease[2]) >= 14931 ? 3 : 2;
+		return 1;
+	}
+	if ("CI" in env) {
+		if ([
+			"GITHUB_ACTIONS",
+			"GITEA_ACTIONS",
+			"CIRCLECI"
+		].some((key) => key in env)) return 3;
+		if ([
+			"TRAVIS",
+			"APPVEYOR",
+			"GITLAB_CI",
+			"BUILDKITE",
+			"DRONE"
+		].some((sign) => sign in env) || env.CI_NAME === "codeship") return 1;
+		return min;
+	}
+	if ("TEAMCITY_VERSION" in env) return /^(9\.(0*[1-9]\d*)\.|\d{2,}\.)/.test(env.TEAMCITY_VERSION ?? "") ? 1 : 0;
+	if ((env.COLORTERM ?? "") === "truecolor") return 3;
+	if ((env.TERM ?? "") === "xterm-kitty" || (env.TERM ?? "") === "xterm-ghostty" || (env.TERM ?? "") === "wezterm") return 3;
+	if ("TERM_PROGRAM" in env) {
+		const version = Number.parseInt((env.TERM_PROGRAM_VERSION || "").split(".")[0], 10);
+		switch (env.TERM_PROGRAM) {
+			case "iTerm.app": return version >= 3 ? 3 : 2;
+			case "Apple_Terminal": return 2;
+		}
+	}
+	if (/-256(color)?$/i.test(env.TERM ?? "")) return 2;
+	if (/^screen|^xterm|^vt100|^vt220|^rxvt|color|ansi|cygwin|linux/i.test(env.TERM ?? "")) return 1;
+	if ("COLORTERM" in env) return 1;
+	return min;
+}
+function createSupportsColor(stream, options = {}) {
+	const internalOptions = { ...options };
+	if (stream?.isTTY !== void 0) internalOptions.streamIsTTY = stream.isTTY;
+	return translateLevel(supportsColorInternal(Boolean(stream), internalOptions));
+}
+
+//#endregion
 //#region src/color.ts
-const DEFAULT_COLOR_LEVEL = supportsColor ? supportsColor.level : 0;
+const defaultColorSupport = createSupportsColor(process.stdout, { sniffFlags: false });
+const DEFAULT_COLOR_LEVEL = defaultColorSupport ? defaultColorSupport.level : 0;
 function getColorLevel(mode) {
 	if (mode === "always") return 3;
 	if (mode === "never") return 0;
@@ -201,12 +287,12 @@ var Command = class {
 	/**
 	* 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}.
+	* @param handler The function that receives parsed option values, including positional arguments by name, and the current [`ExecutionContext`]{@link ExecutionContext}.
 	* @returns A fluent command builder that is now treated as executable.
 	*/
 	run(handler) {
-		this._handler = function(opts, args, context) {
-			return handler(args, opts, context);
+		this._handler = function(opts, context) {
+			return handler(opts, context);
 		};
 		return this;
 	}
@@ -220,6 +306,12 @@ var App = class extends Command {
 	_author;
 	/** @internal */
 	_globalOptions;
+	/** @internal */
+	_helpConfig;
+	/** @internal */
+	_versionConfig;
+	/** @internal */
+	_colorConfig;
 	/**
 	* Applies metadata to the root app in one call.
 	*
@@ -244,14 +336,41 @@ var App = class extends Command {
 		this._bin = binaryName;
 		return this;
 	}
+	version(versionOrConfig) {
+		if (typeof versionOrConfig === "string") {
+			this._version = versionOrConfig;
+			return this;
+		}
+		this._versionConfig = {
+			...this._versionConfig ?? {},
+			...versionOrConfig
+		};
+		return this;
+	}
+	/**
+	* Configures the built-in help command and global option.
+	*
+	* @param config Built-in help settings such as the displayed name, aliases, and whether the command or option should be disabled.
+	* @returns The same fluent app builder with the help command and option configuration applied.
+	*/
+	help(config) {
+		this._helpConfig = {
+			...this._helpConfig ?? {},
+			...config
+		};
+		return this;
+	}
 	/**
-	* Sets the application version surfaced by the built-in version command.
+	* Configures the built-in color global option.
 	*
-	* @param version The version string to display.
-	* @returns The same fluent app builder with the version applied.
+	* @param config Built-in color option settings such as the displayed name, aliases, and whether the option should be disabled.
+	* @returns The same fluent app builder with the color option configuration applied.
 	*/
-	version(version) {
-		this._version = version;
+	color(config) {
+		this._colorConfig = {
+			...this._colorConfig ?? {},
+			...config
+		};
 		return this;
 	}
 	/**
@@ -339,7 +458,7 @@ var App = class extends Command {
 	/**
 	* 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}.
+	* @param handler The function that receives parsed option values including custom global options and positional arguments by name, and the current [`ExecutionContext`]{@link ExecutionContext}.
 	* @returns A fluent app builder that is now treated as executable.
 	*/
 	run(handler) {
@@ -352,7 +471,7 @@ var App = class extends Command {
 	* @returns The numeric exit code returned by the resolved command handler, or `0` when the handler does not return one.
 	*/
 	async execute(args = process.argv.slice(2)) {
-		const { executeApp } = await import("./run-C903J5ca.mjs");
+		const { executeApp } = await import("./run-DEkBUX4b.mjs");
 		const code = await executeApp(this, args);
 		process.exitCode = code;
 		return code;