cli-api 0.1.1 → 0.2.0

package/dist/interfaces-COq24bNI.mjs

@@ -0,0 +1,391 @@
+import { Chalk, supportsColor } from "chalk";
+
+//#region src/color.ts
+const DEFAULT_COLOR_LEVEL = supportsColor ? supportsColor.level : 0;
+function getColorLevel(mode) {
+	if (mode === "always") return 3;
+	if (mode === "never") return 0;
+	return DEFAULT_COLOR_LEVEL;
+}
+function createChalk(mode = "auto") {
+	return new Chalk({ level: getColorLevel(mode) });
+}
+
+//#endregion
+//#region src/interfaces.ts
+let OptType = /* @__PURE__ */ function(OptType$1) {
+	OptType$1[OptType$1["STRING"] = 0] = "STRING";
+	OptType$1[OptType$1["BOOL"] = 1] = "BOOL";
+	OptType$1[OptType$1["INT"] = 2] = "INT";
+	OptType$1[OptType$1["FLOAT"] = 3] = "FLOAT";
+	/** A string, truncated and converted to lowercase. */
+	OptType$1[OptType$1["ENUM"] = 4] = "ENUM";
+	/** File must be readable. Single dash will be converted to STDIN. */
+	OptType$1[OptType$1["INPUT_FILE"] = 5] = "INPUT_FILE";
+	/** Directory must be readable. */
+	OptType$1[OptType$1["INPUT_DIRECTORY"] = 6] = "INPUT_DIRECTORY";
+	/** File's directory must exist and be writeable. Single dash will be converted to STDOUT. */
+	OptType$1[OptType$1["OUTPUT_FILE"] = 7] = "OUTPUT_FILE";
+	OptType$1[OptType$1["OUTPUT_DIRECTORY"] = 8] = "OUTPUT_DIRECTORY";
+	/** An empty or non-existent directory. */
+	OptType$1[OptType$1["EMPTY_DIRECTORY"] = 9] = "EMPTY_DIRECTORY";
+	return OptType$1;
+}({});
+/**
+* Per-invocation execution state exposed to command handlers.
+*/
+var ExecutionContext = class {
+	_app;
+	_commandPath;
+	_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, colorMode = "auto", path = []) {
+		this._app = app;
+		this._commandPath = path;
+		this._chalk = createChalk(colorMode);
+	}
+	/**
+	* Gets the root app for the current invocation.
+	*
+	* @returns The app definition being executed.
+	*/
+	get app() {
+		return this._app;
+	}
+	/**
+	* Gets the resolved command path for the current invocation.
+	*
+	* @returns The command names from the app root to the executing command.
+	*/
+	get commandPath() {
+		return this._commandPath;
+	}
+	/**
+	* 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() {
+		return this._chalk;
+	}
+	/**
+	* Gets the resolved color support level configured for the current invocation.
+	*
+	* @returns The active color level from `0` to `3`.
+	*/
+	get colorLevel() {
+		return this._chalk.level;
+	}
+};
+var Command = class {
+	_name;
+	_alias;
+	_description;
+	_longDescription;
+	_options;
+	_positonals;
+	_subCommands;
+	_handler;
+	constructor(name) {
+		this._name = name;
+	}
+	get name() {
+		return this._name;
+	}
+	get alias() {
+		return this._alias;
+	}
+	get description() {
+		return this._description;
+	}
+	get longDescription() {
+		return this._longDescription;
+	}
+	get options() {
+		return this._options;
+	}
+	get positonals() {
+		return this._positonals;
+	}
+	get subCommands() {
+		return this._subCommands;
+	}
+	get handler() {
+		return this._handler;
+	}
+	setLongDescription(longDescription) {
+		this._longDescription = longDescription;
+	}
+	/**
+	* 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) {
+		this._alias = aliases.length <= 1 ? aliases[0] : aliases;
+		return 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, longDescription) {
+		this._description = description;
+		if (longDescription !== void 0) this._longDescription = longDescription;
+		return 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(name, config) {
+		(this._options ??= []).push({
+			name,
+			...config ?? {},
+			valueNotRequired: true,
+			type: OptType.BOOL
+		});
+		return this;
+	}
+	/**
+	* 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(name, config) {
+		(this._options ??= []).push({
+			name,
+			...config ?? {}
+		});
+		return this;
+	}
+	/**
+	* 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(name, config) {
+		(this._positonals ??= []).push({
+			name,
+			...config ?? {}
+		});
+		return this;
+	}
+	/**
+	* 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(subCommand) {
+		(this._subCommands ??= []).push(subCommand);
+		return this;
+	}
+	/**
+	* 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(handler) {
+		this._handler = function(opts, args, context) {
+			return handler(args, opts, context);
+		};
+		return this;
+	}
+};
+var App = class extends Command {
+	/** @internal */
+	_bin;
+	/** @internal */
+	_version;
+	/** @internal */
+	_author;
+	/** @internal */
+	_globalOptions;
+	/**
+	* 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) {
+		if (config.bin !== void 0) this.bin(config.bin);
+		if (config.version !== void 0) this.version(config.version);
+		if (config.author !== void 0) this.author(config.author);
+		if (config.description !== void 0) this.describe(config.description, config.longDescription);
+		else if (config.longDescription !== void 0) this.setLongDescription(config.longDescription);
+		return 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) {
+		this._bin = binaryName;
+		return 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) {
+		this._version = version;
+		return 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) {
+		this._author = author;
+		return 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) {
+		return super.aliases(...aliases);
+	}
+	/**
+	* 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, longDescription) {
+		return super.describe(description, longDescription);
+	}
+	/**
+	* 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(name, config) {
+		return super.flag(name, config);
+	}
+	/**
+	* 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(name, config) {
+		return super.opt(name, config);
+	}
+	/**
+	* 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(name, config) {
+		(this._globalOptions ??= []).push({
+			name,
+			...config ?? {}
+		});
+		return 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(name, config) {
+		return super.arg(name, config);
+	}
+	/**
+	* 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(subCommand) {
+		return super.command(subCommand);
+	}
+	/**
+	* 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(handler) {
+		return super.run(handler);
+	}
+	/**
+	* 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.
+	*/
+	async execute(args = process.argv.slice(2)) {
+		const { executeApp } = await import("./run-C903J5ca.mjs");
+		const code = await executeApp(this, args);
+		process.exitCode = code;
+		return code;
+	}
+};
+/**
+* Checks whether a command or app contains nested sub-commands.
+*
+* @param value The command or app to inspect.
+* @returns `true` when the value has sub-commands.
+*/
+function hasSubCommands(value) {
+	return Array.isArray(value.subCommands);
+}
+/**
+* Checks whether a command or app can be executed directly.
+*
+* @param value The command or app to inspect.
+* @returns `true` when the value has an executable handler.
+*/
+function isExecutable(value) {
+	return typeof value.handler === "function" || Object.prototype.hasOwnProperty.call(value, "execute");
+}
+/**
+* Resolves the executable handler for an object-style or fluent command/app.
+*
+* @param value The command or app to inspect.
+* @returns The handler function when one exists, otherwise `undefined`.
+*/
+function getExecuteHandler(value) {
+	if (typeof value.handler === "function") return value.handler;
+	if (Object.prototype.hasOwnProperty.call(value, "execute")) return value.execute;
+}
+
+//#endregion
+export { getExecuteHandler as a, createChalk as c, OptType as i, Command as n, hasSubCommands as o, ExecutionContext as r, isExecutable as s, App as t };