gunshi 0.35.1 → 0.35.2

package/lib/core-CbE1I4Jl.js

@@ -0,0 +1,518 @@
+import { i as NOOP, r as CLI_OPTIONS_DEFAULT, t as createCommandContext } from "./context-CAPhwgJJ.js";
+import { n as kebabnize } from "./utils-BKhsrjPW.js";
+import { create, getCommandSubCommands, isLazyCommand, resolveLazyCommand } from "./utils.js";
+import { a as parseArgs, i as resolveArgs, n as ArgsValidationErrorKeys, t as ArgsValidationError } from "./resolver-UFOtObbe.js";
+import { n as CommandNotFoundErrorKeys, r as hasPriorityValidationError, t as CommandNotFoundError } from "./error-xSnOOdnr.js";
+//#region src/decorators.ts
+/**
+* @author kazuya kawaguchi (a.k.a. kazupon)
+* @license MIT
+*/
+const EMPTY_RENDERER = () => Promise.resolve("");
+/**
+* Factory function for creating a decorators manager.
+*
+* @returns A new decorators manager instance
+*/
+function createDecorators() {
+	/**
+	* private states
+	*/
+	const headerDecorators = [];
+	const usageDecorators = [];
+	const validationDecorators = [];
+	const commandDecorators = [];
+	/**
+	* helper function for building renderers
+	*/
+	function buildRenderer(decorators, defaultRenderer) {
+		if (decorators.length === 0) return defaultRenderer;
+		let renderer = defaultRenderer;
+		for (const decorator of decorators) {
+			const previousRenderer = renderer;
+			renderer = (ctx) => decorator(previousRenderer, ctx);
+		}
+		return renderer;
+	}
+	/**
+	* public interfaces
+	*/
+	return Object.freeze({
+		addHeaderDecorator(decorator) {
+			headerDecorators.push(decorator);
+		},
+		addUsageDecorator(decorator) {
+			usageDecorators.push(decorator);
+		},
+		addValidationErrorsDecorator(decorator) {
+			validationDecorators.push(decorator);
+		},
+		addCommandDecorator(decorator) {
+			commandDecorators.push(decorator);
+		},
+		get commandDecorators() {
+			return [...commandDecorators];
+		},
+		getHeaderRenderer() {
+			return buildRenderer(headerDecorators, EMPTY_RENDERER);
+		},
+		getUsageRenderer() {
+			return buildRenderer(usageDecorators, EMPTY_RENDERER);
+		},
+		getValidationErrorsRenderer() {
+			if (validationDecorators.length === 0) return EMPTY_RENDERER;
+			let renderer = EMPTY_RENDERER;
+			for (const decorator of validationDecorators) {
+				const previousRenderer = renderer;
+				renderer = (ctx, error) => decorator(previousRenderer, ctx, error);
+			}
+			return renderer;
+		}
+	});
+}
+//#endregion
+//#region src/plugin/context.ts
+/**
+* @author kazuya kawaguchi (a.k.a. kazupon)
+* @license MIT
+*/
+/**
+* Factory function for creating a plugin context.
+*
+* @typeParam G - A type extending {@linkcode GunshiParams} to specify the shape of command parameters.
+*
+* @param decorators - A {@linkcode Decorators} instance.
+* @param initialSubCommands - Initial sub commands map.
+* @returns A new {@linkcode PluginContext} instance.
+*/
+function createPluginContext(decorators, initialSubCommands) {
+	/**
+	* private states
+	*/
+	const globalOptions = /* @__PURE__ */ new Map();
+	const subCommands = new Map(initialSubCommands || []);
+	/**
+	* public interfaces
+	*/
+	return Object.freeze({
+		get globalOptions() {
+			return new Map(globalOptions);
+		},
+		addGlobalOption(name, schema) {
+			if (!name) throw new Error("Option name must be a non-empty string");
+			if (globalOptions.has(name)) throw new Error(`Global option '${name}' is already registered`);
+			globalOptions.set(name, schema);
+		},
+		get subCommands() {
+			return new Map(subCommands);
+		},
+		addCommand(name, command) {
+			if (!name) throw new Error("Command name must be a non-empty string");
+			if (subCommands.has(name)) throw new Error(`Command '${name}' is already registered`);
+			subCommands.set(name, command);
+		},
+		hasCommand(name) {
+			return subCommands.has(name);
+		},
+		decorateHeaderRenderer(decorator) {
+			decorators.addHeaderDecorator(decorator);
+		},
+		decorateUsageRenderer(decorator) {
+			decorators.addUsageDecorator(decorator);
+		},
+		decorateValidationErrorsRenderer(decorator) {
+			decorators.addValidationErrorsDecorator(decorator);
+		},
+		decorateCommand(decorator) {
+			decorators.addCommandDecorator(decorator);
+		}
+	});
+}
+//#endregion
+//#region src/plugin/dependency.ts
+/**
+* @author kazuya kawaguchi (a.k.a. kazupon)
+* @license MIT
+*/
+/**
+* Resolve plugin dependencies using topological sort
+*
+* @param plugins - Array of plugins to resolve
+* @returns Array of plugins sorted by dependencies
+*/
+function resolveDependencies(plugins) {
+	const sorted = [];
+	const visited = /* @__PURE__ */ new Set();
+	const visiting = /* @__PURE__ */ new Set();
+	const pluginMap = /* @__PURE__ */ new Map();
+	for (const plugin of plugins) if (plugin.id) {
+		if (pluginMap.has(plugin.id)) console.warn(`Duplicate plugin id detected: \`${plugin.id}\``);
+		pluginMap.set(plugin.id, plugin);
+	}
+	function visit(plugin) {
+		if (!plugin.id) return;
+		if (visited.has(plugin.id)) return;
+		if (visiting.has(plugin.id)) throw new Error(`Circular dependency detected: \`${[...visiting].join(` -> `) + " -> " + plugin.id}\``);
+		visiting.add(plugin.id);
+		const deps = plugin.dependencies || [];
+		for (const dep of deps) {
+			const depId = typeof dep === "string" ? dep : dep.id;
+			const isOptional = typeof dep === "string" ? false : dep.optional || false;
+			const depPlugin = pluginMap.get(depId);
+			if (!depPlugin && !isOptional) throw new Error(`Missing required dependency: \`${depId}\` on \`${plugin.id}\``);
+			if (depPlugin) visit(depPlugin);
+		}
+		visiting.delete(plugin.id);
+		visited.add(plugin.id);
+		sorted.push(plugin);
+	}
+	for (const plugin of plugins) visit(plugin);
+	return sorted;
+}
+//#endregion
+//#region src/cli/core.ts
+/**
+* @author kazuya kawaguchi (a.k.a. kazupon)
+* @license MIT
+*/
+/**
+* Run the command.
+*
+* @typeParam G - A type extending {@linkcode GunshiParams} to specify the shape of command and cli options.
+*
+* @param argv - Command line arguments
+* @param entry - A {@link Command | entry command}, an {@link CommandRunner | inline command runner}, or a {@link LazyCommand | lazily-loaded command}
+* @param options - A {@link CliOptions | CLI options}
+* @param plugins - An array of {@link Plugin | plugins} to be applied
+* @returns A rendered usage or undefined. if you will use {@link CliOptions.usageSilent} option, it will return rendered usage string.
+*/
+async function cliCore(argv, entry, options, plugins) {
+	const decorators = createDecorators();
+	const pluginContext = createPluginContext(decorators, createInitialSubCommands(options, entry));
+	const resolvedPlugins = await applyPlugins(pluginContext, [...plugins, ...options.plugins || []]);
+	const cliOptions = normalizeCliOptions(options, decorators, pluginContext);
+	const tokens = parseArgs(argv);
+	const resolved = resolveCommandTree(tokens, entry, cliOptions);
+	const { commandName: name, command, callMode, commandPath, depth, levelSubCommands } = resolved;
+	let targetCommand = command;
+	let targetCommandName = name;
+	let targetCallMode = callMode;
+	let targetCommandPath = commandPath;
+	let targetDepth = depth;
+	let targetOmitted = resolved.omitted;
+	let targetLevelSubCommands = levelSubCommands;
+	const additionalValidationErrors = [];
+	if (!targetCommand) {
+		if (!resolved.parentCommand || !resolved.unresolvedCommandName) throw new Error(`Command not found: ${name || ""}`);
+		targetCommand = resolved.parentCommand;
+		targetCommandName = resolved.parentCommandName;
+		targetCommandPath = resolved.parentCommandPath || [];
+		targetDepth = targetCommandPath.length;
+		targetCallMode = targetDepth > 0 ? "subCommand" : "entry";
+		targetOmitted = false;
+		targetLevelSubCommands = resolved.parentSubCommands;
+		additionalValidationErrors.push(createCommandNotFoundError(resolved));
+	}
+	if (targetLevelSubCommands) cliOptions.subCommands = targetLevelSubCommands;
+	const resolvedCommand = isLazyCommand(targetCommand) ? await resolveLazyCommand(targetCommand, targetCommandName, true) : targetCommand;
+	const args = resolveArguments(pluginContext, getCommandArgs(resolvedCommand));
+	const skipPositional = targetDepth > 0 ? targetDepth - 1 : -1;
+	const { explicit, values, positionals, rest, error } = resolveArgs(args, tokens, {
+		shortGrouping: true,
+		toKebab: resolvedCommand.toKebab,
+		skipPositional
+	});
+	const validationError = mergeValidationErrors(error, [...additionalValidationErrors, ...cliOptions.strict ? createUnknownOptionErrors(findUnknownOptions(args, tokens, { toKebab: resolvedCommand.toKebab })) : []]);
+	return await executeCommand(resolvedCommand, await createCommandContext({
+		args,
+		explicit,
+		values,
+		positionals,
+		rest,
+		argv,
+		tokens,
+		omitted: targetOmitted,
+		callMode: targetCallMode,
+		commandPath: targetCommandPath,
+		command: resolvedCommand,
+		extensions: getPluginExtensions(resolvedPlugins),
+		validationError,
+		cliOptions
+	}), decorators.commandDecorators);
+}
+async function applyPlugins(pluginContext, plugins) {
+	const sortedPlugins = resolveDependencies(plugins);
+	try {
+		for (const plugin of sortedPlugins)
+ /**
+		* NOTE(kazupon):
+		* strictly `Args` are not required for plugin installation.
+		* because the strictly `Args` required by each plugin are unknown,
+		* and the plugin side can not know what the user will specify.
+		*/
+		await plugin(pluginContext);
+	} catch (error) {
+		console.error("Error loading plugin:", error.message);
+	}
+	return sortedPlugins;
+}
+function getCommandArgs(cmd) {
+	if (isLazyCommand(cmd)) return cmd.args || create();
+	else if (typeof cmd === "object") return cmd.args || create();
+	else return create();
+}
+function resolveArguments(pluginContext, args) {
+	return Object.assign(create(), Object.fromEntries(pluginContext.globalOptions), args);
+}
+const NEGATABLE_OPTION_PREFIX = "no-";
+function findUnknownOptions(args, tokens, options) {
+	const knownLongOptions = /* @__PURE__ */ new Set();
+	const knownShortOptions = /* @__PURE__ */ new Set();
+	const knownNegatableOptions = /* @__PURE__ */ new Set();
+	const knownLongOptionCandidates = /* @__PURE__ */ new Set();
+	const longOptionCandidates = [];
+	function addLongOptionCandidate(name) {
+		const candidate = `--${name}`;
+		if (knownLongOptionCandidates.has(candidate)) return;
+		knownLongOptionCandidates.add(candidate);
+		longOptionCandidates.push(candidate);
+	}
+	for (const [name, schema] of Object.entries(args)) {
+		if (schema.type === "positional") continue;
+		const optionName = resolveOptionName(name, schema, options);
+		knownLongOptions.add(optionName);
+		addLongOptionCandidate(optionName);
+		if (schema.short) knownShortOptions.add(schema.short);
+		if (schema.type === "boolean" && schema.negatable) {
+			const negatableOptionName = `${NEGATABLE_OPTION_PREFIX}${optionName}`;
+			knownNegatableOptions.add(negatableOptionName);
+			addLongOptionCandidate(negatableOptionName);
+		}
+	}
+	const unknownOptions = [];
+	for (const token of tokens) {
+		if (token.kind === "option-terminator") break;
+		if (token.kind !== "option" || !token.name || !token.rawName) continue;
+		const isLongOption = token.rawName.startsWith("--");
+		if (isLongOption) {
+			if (knownLongOptions.has(token.name) || knownNegatableOptions.has(token.name)) continue;
+		} else if (knownShortOptions.has(token.name)) continue;
+		unknownOptions.push({
+			rawName: token.rawName,
+			name: token.name,
+			candidates: isLongOption ? longOptionCandidates : []
+		});
+	}
+	return unknownOptions;
+}
+function resolveOptionName(name, schema, options) {
+	return options.toKebab || schema.toKebab ? kebabnize(name) : name;
+}
+function createUnknownOptionErrors(unknownOptions) {
+	return unknownOptions.map(({ rawName, name, candidates }) => {
+		return new ArgsValidationError(`Unknown option: ${rawName}`, {
+			code: ArgsValidationErrorKeys.unknownOption,
+			values: {
+				rawName,
+				name,
+				candidates
+			}
+		});
+	});
+}
+function mergeValidationErrors(error, additionalErrors) {
+	if (additionalErrors.length === 0) return error;
+	return new AggregateError(error ? [...error.errors, ...additionalErrors] : additionalErrors, error?.message || additionalErrors[0]?.message);
+}
+const isObject = (val) => val !== null && typeof val === "object";
+function createInitialSubCommands(options, entryCmd) {
+	const hasSubCommands = options.subCommands ? options.subCommands instanceof Map ? options.subCommands.size > 0 : isObject(options.subCommands) && Object.keys(options.subCommands).length > 0 : false;
+	const subCommands = new Map(options.subCommands instanceof Map ? options.subCommands : []);
+	if (!(options.subCommands instanceof Map) && isObject(options.subCommands)) for (const [name, cmd] of Object.entries(options.subCommands)) subCommands.set(name, cmd);
+	if (hasSubCommands) {
+		if (isLazyCommand(entryCmd)) {
+			const entryCopy = Object.assign((...args) => entryCmd(...args), entryCmd, { entry: true });
+			subCommands.set(resolveEntryName(entryCopy), entryCopy);
+		} else if (typeof entryCmd === "object") {
+			const entryCopy = Object.assign(create(), entryCmd, { entry: true });
+			subCommands.set(resolveEntryName(entryCopy), entryCopy);
+		} else if (typeof entryCmd === "function") {
+			const name = entryCmd.name || "(anonymous)";
+			subCommands.set(name, {
+				run: entryCmd,
+				name,
+				entry: true
+			});
+		}
+	}
+	return subCommands;
+}
+function normalizeCliOptions(options, decorators, pluginContext) {
+	const subCommands = new Map(pluginContext.subCommands);
+	const resolvedOptions = Object.assign(create(), CLI_OPTIONS_DEFAULT, options, { subCommands });
+	if (resolvedOptions.renderHeader === void 0) resolvedOptions.renderHeader = decorators.getHeaderRenderer();
+	if (resolvedOptions.renderUsage === void 0) resolvedOptions.renderUsage = decorators.getUsageRenderer();
+	if (resolvedOptions.renderValidationErrors === void 0) resolvedOptions.renderValidationErrors = decorators.getValidationErrorsRenderer();
+	return resolvedOptions;
+}
+function getPositionalTokens(tokens) {
+	return tokens.filter((t) => t.kind === "positional").map((t) => t.value).filter((v) => !!v);
+}
+function resolveCommandTree(tokens, entry, options) {
+	const positionals = getPositionalTokens(tokens);
+	function resolveAsEntry() {
+		if (typeof entry === "function") if ("commandName" in entry && entry.commandName) return {
+			commandName: entry.commandName,
+			command: entry,
+			callMode: "entry",
+			commandPath: [],
+			depth: 0,
+			omitted: options.subCommands.size > 0 && !positionals[0],
+			levelSubCommands: options.subCommands.size > 0 ? options.subCommands : void 0
+		};
+		else return {
+			command: {
+				run: entry,
+				entry: true
+			},
+			callMode: "entry",
+			commandPath: [],
+			depth: 0,
+			omitted: options.subCommands.size > 0 && !positionals[0],
+			levelSubCommands: options.subCommands.size > 0 ? options.subCommands : void 0
+		};
+		else if (typeof entry === "object") return {
+			commandName: resolveEntryName(entry),
+			command: entry,
+			callMode: "entry",
+			commandPath: [],
+			depth: 0,
+			omitted: options.subCommands.size > 0 && !positionals[0],
+			levelSubCommands: options.subCommands.size > 0 ? options.subCommands : void 0
+		};
+		else return {
+			callMode: "unexpected",
+			commandPath: [],
+			depth: 0,
+			omitted: false,
+			levelSubCommands: void 0
+		};
+	}
+	if (positionals.length === 0 || options.subCommands.size === 0) return resolveAsEntry();
+	let currentSubCommands = options.subCommands;
+	let resolvedCommand;
+	let resolvedName;
+	const commandPath = [];
+	let depth = 0;
+	for (let i = 0; i < positionals.length; i++) {
+		const token = positionals[i];
+		const cmd = currentSubCommands.get(token);
+		if (cmd == null) {
+			if (depth === 0) {
+				if (options.fallbackToEntry) return resolveAsEntry();
+				const parent = resolveAsEntry();
+				return {
+					commandName: token,
+					callMode: "unexpected",
+					commandPath: [],
+					depth: 0,
+					omitted: false,
+					levelSubCommands: void 0,
+					unresolvedCommandName: token,
+					parentCommand: parent.command,
+					parentCommandName: parent.commandName,
+					parentCommandPath: [],
+					parentSubCommands: options.subCommands
+				};
+			}
+			return {
+				commandName: token,
+				callMode: "unexpected",
+				commandPath: [...commandPath],
+				depth,
+				omitted: false,
+				levelSubCommands: void 0,
+				unresolvedCommandName: token,
+				parentCommand: resolvedCommand,
+				parentCommandName: resolvedName,
+				parentCommandPath: [...commandPath],
+				parentSubCommands: currentSubCommands
+			};
+		}
+		let resolved = cmd;
+		if (typeof cmd === "function" && cmd.commandName == null) resolved = Object.assign((...args) => cmd(...args), cmd, { commandName: token });
+		else if (typeof cmd === "object" && cmd.name == null) resolved = Object.assign(create(), cmd, { name: token });
+		resolvedCommand = resolved;
+		resolvedName = token;
+		commandPath.push(token);
+		depth++;
+		const nestedSubCommands = getCommandSubCommands(cmd);
+		if (nestedSubCommands && nestedSubCommands.size > 0) currentSubCommands = nestedSubCommands;
+		else break;
+	}
+	if (!resolvedCommand) return resolveAsEntry();
+	const resolvedSubCommands = getCommandSubCommands(resolvedCommand);
+	const omitted = resolvedSubCommands != null && resolvedSubCommands.size > 0;
+	let levelSubCommands;
+	if (omitted && resolvedSubCommands) {
+		levelSubCommands = new Map(resolvedSubCommands);
+		let entryCopy;
+		if (typeof resolvedCommand === "function") entryCopy = Object.assign((...args) => resolvedCommand(...args), resolvedCommand, { entry: true });
+		else entryCopy = Object.assign(create(), resolvedCommand, { entry: true });
+		levelSubCommands.set(resolvedName || resolveEntryName(entryCopy), entryCopy);
+	}
+	return {
+		commandName: resolvedName,
+		command: resolvedCommand,
+		callMode: depth > 0 ? "subCommand" : "entry",
+		commandPath,
+		depth,
+		omitted,
+		levelSubCommands
+	};
+}
+function createCommandNotFoundError(resolved) {
+	const commandName = resolved.unresolvedCommandName || resolved.commandName || "";
+	return new CommandNotFoundError(`Command not found: ${commandName}`, {
+		code: CommandNotFoundErrorKeys.notFound,
+		values: { commandName },
+		commandName,
+		candidates: [...resolved.parentSubCommands?.keys() || []],
+		commandPath: resolved.parentCommandPath || []
+	});
+}
+function resolveEntryName(entry) {
+	return isLazyCommand(entry) ? entry.commandName || "(anonymous)" : entry.name || "(anonymous)";
+}
+function getPluginExtensions(plugins) {
+	const extensions = create();
+	for (const plugin of plugins) if (plugin.extension) {
+		const key = plugin.id;
+		if (extensions[key]) console.warn(`Plugin "${key}" is already installed. Ignore it for command context extending.`);
+		else extensions[key] = plugin.extension;
+	}
+	return extensions;
+}
+async function executeCommand(cmd, ctx, decorators) {
+	const commandRunner = cmd.run || NOOP;
+	const baseRunner = (ctx) => {
+		if (hasPriorityValidationError(ctx.validationError)) throw ctx.validationError;
+		return commandRunner(ctx);
+	};
+	const decoratedRunner = decorators.reduceRight((runner, decorator) => decorator(runner), baseRunner);
+	try {
+		if (ctx.env.onBeforeCommand) await ctx.env.onBeforeCommand(ctx);
+		const result = await decoratedRunner(ctx);
+		if (ctx.env.onAfterCommand) await ctx.env.onAfterCommand(ctx, result);
+		return typeof result === "string" ? result : void 0;
+	} catch (error) {
+		if (ctx.env.onErrorCommand) try {
+			await ctx.env.onErrorCommand(ctx, error);
+		} catch (hookError) {
+			console.error("Error in onErrorCommand hook:", hookError);
+		}
+		throw error;
+	}
+}
+//#endregion
+export { cliCore as t };

package/lib/definition.d.ts

@@ -1,5 +1,5 @@
-import { i as Args, n as ArgSchema, r as ArgValues } from "./resolver-mxPNDBm_.js";
-import { C as NormalizeToGunshiParams, _ as ExtractArgs, b as GunshiParamsConstraint, d as CommandLoader, f as CommandRunner, h as ExtendContext, m as DefaultGunshiParams, r as Command, v as ExtractExtensions, w as Prettify, x as LazyCommand, y as GunshiParams } from "./types-DZ0S_FSe.js";
+import { i as Args, n as ArgSchema, r as ArgValues } from "./resolver-CgkhQ6Tt.js";
+import { C as NormalizeToGunshiParams, _ as ExtractArgs, b as GunshiParamsConstraint, d as CommandLoader, f as CommandRunner, h as ExtendContext, m as DefaultGunshiParams, r as Command, v as ExtractExtensions, w as Prettify, x as LazyCommand, y as GunshiParams } from "./types-CD5eRJFK.js";
 import { CommandContextParams, createCommandContext } from "./context.js";
 
 //#region src/definition.d.ts

package/lib/definition.js

@@ -1,4 +1,4 @@
-import { createCommandContext } from "./context.js";
+import { t as createCommandContext } from "./context-CAPhwgJJ.js";
 //#region src/definition.ts
 /**
 * @author kazuya kawaguchi (a.k.a. kazupon)

package/lib/error-6srXBX7u.d.ts

@@ -0,0 +1,87 @@
+import { m as DefaultGunshiParams, n as CliOptions } from "./types-CD5eRJFK.js";
+
+//#region src/constants.d.ts
+/**
+* @author kazuya kawaguchi (a.k.a. kazupon)
+* @license MIT
+*/
+declare const ANONYMOUS_COMMAND_NAME = "(anonymous)";
+declare const CLI_OPTIONS_DEFAULT: CliOptions<DefaultGunshiParams>;
+//#endregion
+//#region src/error.d.ts
+/**
+ * @author kazuya kawaguchi (a.k.a. kazupon)
+ * @license MIT
+ */
+/**
+ * Command not found error resource keys.
+ */
+declare const CommandNotFoundErrorKeys: {
+  readonly notFound: "err:cmd:not-found";
+};
+/**
+ * Command not found error code.
+ */
+type CommandNotFoundErrorCode = (typeof CommandNotFoundErrorKeys)[keyof typeof CommandNotFoundErrorKeys];
+/**
+ * Options for {@link CommandNotFoundError}.
+ */
+type CommandNotFoundErrorOptions = {
+  /**
+   * Localization resource key for command-not-found rendering.
+   */
+  code?: CommandNotFoundErrorCode;
+  /**
+   * Values used when localizing the message.
+   */
+  values?: Record<string, unknown>;
+  /**
+   * The command name that could not be resolved.
+   */
+  commandName: string;
+  /**
+   * Command names available at the same level.
+   */
+  candidates?: readonly string[];
+  /**
+   * Parent command path where resolution failed.
+   */
+  commandPath?: readonly string[];
+  /**
+   * Underlying cause.
+   */
+  cause?: unknown;
+};
+/**
+ * Error raised when a command cannot be resolved.
+ */
+declare class CommandNotFoundError extends Error {
+  readonly code?: CommandNotFoundErrorCode;
+  readonly values: Record<string, unknown>;
+  readonly commandName: string;
+  readonly candidates: readonly string[];
+  readonly commandPath: readonly string[];
+  /**
+   * Create a command-not-found error.
+   *
+   * @param message - Fallback error message
+   * @param options - Command-not-found metadata
+   */
+  constructor(message: string, options: CommandNotFoundErrorOptions);
+}
+/**
+ * Check whether an error is a {@link CommandNotFoundError}.
+ *
+ * @param error - An unknown error
+ * @returns `true` if the error is a {@link CommandNotFoundError}
+ */
+declare function isCommandNotFoundError(error: unknown): error is CommandNotFoundError;
+/**
+ * Check whether validation errors should be handled before version, help, or command execution.
+ *
+ * @param error - An aggregate validation error
+ * @returns `true` if the validation error must be handled with priority
+ */
+declare function hasPriorityValidationError(error: AggregateError | undefined): boolean;
+//#endregion
+export { hasPriorityValidationError as a, CLI_OPTIONS_DEFAULT as c, CommandNotFoundErrorOptions as i, CommandNotFoundErrorCode as n, isCommandNotFoundError as o, CommandNotFoundErrorKeys as r, ANONYMOUS_COMMAND_NAME as s, CommandNotFoundError as t };

package/lib/error-xSnOOdnr.js

@@ -0,0 +1,65 @@
+import { n as ArgsValidationErrorKeys, r as isArgsValidationError } from "./resolver-UFOtObbe.js";
+//#region ../../node_modules/.pnpm/args-tokens@0.28.0/node_modules/args-tokens/lib/index.js
+/**
+* @author kazuya kawaguchi (a.k.a. kazupon)
+* @license MIT
+*/
+/**
+* @author kazuya kawaguchi (a.k.a. kazupon)
+* @license MIT
+*/
+//#endregion
+//#region src/error.ts
+/**
+* @author kazuya kawaguchi (a.k.a. kazupon)
+* @license MIT
+*/
+/**
+* Command not found error resource keys.
+*/
+const CommandNotFoundErrorKeys = { notFound: "err:cmd:not-found" };
+/**
+* Error raised when a command cannot be resolved.
+*/
+var CommandNotFoundError = class extends Error {
+	code;
+	values;
+	commandName;
+	candidates;
+	commandPath;
+	/**
+	* Create a command-not-found error.
+	*
+	* @param message - Fallback error message
+	* @param options - Command-not-found metadata
+	*/
+	constructor(message, options) {
+		super(message, { cause: options.cause });
+		this.name = "CommandNotFoundError";
+		this.code = options.code;
+		this.values = options.values || {};
+		this.commandName = options.commandName;
+		this.candidates = options.candidates || [];
+		this.commandPath = options.commandPath || [];
+	}
+};
+/**
+* Check whether an error is a {@link CommandNotFoundError}.
+*
+* @param error - An unknown error
+* @returns `true` if the error is a {@link CommandNotFoundError}
+*/
+function isCommandNotFoundError(error) {
+	return error instanceof CommandNotFoundError;
+}
+/**
+* Check whether validation errors should be handled before version, help, or command execution.
+*
+* @param error - An aggregate validation error
+* @returns `true` if the validation error must be handled with priority
+*/
+function hasPriorityValidationError(error) {
+	return error?.errors.some((error) => isCommandNotFoundError(error) || isArgsValidationError(error) && error.code === ArgsValidationErrorKeys.unknownOption) ?? false;
+}
+//#endregion
+export { isCommandNotFoundError as i, CommandNotFoundErrorKeys as n, hasPriorityValidationError as r, CommandNotFoundError as t };

package/lib/generator.d.ts

@@ -1,4 +1,4 @@
-import { b as GunshiParamsConstraint, m as DefaultGunshiParams, n as CliOptions, r as Command, x as LazyCommand } from "./types-DZ0S_FSe.js";
+import { b as GunshiParamsConstraint, m as DefaultGunshiParams, n as CliOptions, r as Command, x as LazyCommand } from "./types-CD5eRJFK.js";
 
 //#region src/generator.d.ts