gunshi 0.35.0 → 0.35.2

package/lib/{src-B4uHG_qb.js → src-DbfZvEe0.js}

@@ -1,12 +1,20 @@
-import "./constants-CQq1R_68.js";
-import { o as resolveLazyCommand, s as kebabnize } from "./utils-DNVHO9MQ.js";
-import { t as plugin } from "./core-CFEvRYOJ.js";
+import "./context-CAPhwgJJ.js";
+import { n as kebabnize } from "./utils-BKhsrjPW.js";
+import { resolveLazyCommand } from "./utils.js";
+import { n as ArgsValidationErrorKeys, r as isArgsValidationError } from "./resolver-UFOtObbe.js";
+import { i as isCommandNotFoundError } from "./error-xSnOOdnr.js";
+import { t as plugin } from "./plugin-DhJZVIbl.js";
+/**
+* @author kazuya kawaguchi (a.k.a. kazupon)
+* @license MIT
+*/
 /**
 * @author kazuya kawaguchi (a.k.a. kazupon)
 * @license MIT
 */
 const BUILD_IN_PREFIX_AND_KEY_SEPARATOR = `_:`;
 const ARG_PREFIX_AND_KEY_SEPARATOR = `arg:`;
+const ERROR_PREFIX_AND_KEY_SEPARATOR = `err:`;
 const COMMON_ARGS = {
 	help: {
 		type: "boolean",
@@ -35,7 +43,15 @@ var en_US_default = {
 	DEFAULT: "default",
 	CHOICES: "choices",
 	help: "Display this help message",
-	version: "Display this version"
+	version: "Display this version",
+	"err:arg:required-option": "Optional argument {$displayName} is required",
+	"err:arg:required-positional": "Positional argument {$name} is required",
+	"err:arg:invalid-type": "Invalid value for {$displayName}: expected {$expected}",
+	"err:arg:invalid-choice": "Invalid value for {$displayName}: expected one of {$choices}",
+	"err:arg:custom-parse": "Invalid value for {$displayName}: {$reason}",
+	"err:arg:unknown-option": "Unknown option: {$rawName}",
+	"err:cmd:not-found": "Command not found: {$commandName}",
+	"err:suggestion:did-you-mean": "Did you mean {$name}?"
 };
 //#endregion
 //#region ../shared/src/utils.ts
@@ -144,7 +160,8 @@ function makeShortLongOptionPair(schema, name, toKebab) {
 function localizable(ctx, cmd, translate) {
 	async function localize(key, values) {
 		if (translate) return translate(key, values);
-		if (key.startsWith(BUILD_IN_PREFIX_AND_KEY_SEPARATOR)) return en_US_default[key.slice(BUILD_IN_PREFIX_AND_KEY_SEPARATOR.length)] || key;
+		if (key.startsWith(BUILD_IN_PREFIX_AND_KEY_SEPARATOR)) return resolveAndFormatResource(key.slice(BUILD_IN_PREFIX_AND_KEY_SEPARATOR.length), key, values);
+		if (key.startsWith(ERROR_PREFIX_AND_KEY_SEPARATOR)) return resolveAndFormatResource(key, key, values);
 		const namaspacedArgKey = resolveKey(ARG_PREFIX_AND_KEY_SEPARATOR, ctx.name);
 		if (key.startsWith(namaspacedArgKey)) {
 			let argKey = key.slice(namaspacedArgKey.length);
@@ -163,6 +180,21 @@ function localizable(ctx, cmd, translate) {
 	}
 	return localize;
 }
+function resolveAndFormatResource(resourceKey, fallbackKey, values) {
+	return formatResource(en_US_default[resourceKey], values) || fallbackKey;
+}
+/**
+* Format a resource message by replacing placeholder values.
+*
+* @param resource - Resource message template
+* @param values - Placeholder values
+* @returns Formatted resource message
+*/
+function formatResource(resource, values = Object.create(null)) {
+	return resource?.replaceAll(/\{\$(\w+)\}/g, (_, name) => {
+		return values[name] == null ? "" : String(values[name]);
+	});
+}
 //#endregion
 //#region ../shared/src/index.ts
 /**
@@ -525,17 +557,50 @@ function isRequiredSinglePositionalArg(arg) {
 * @author kazuya kawaguchi (a.k.a. kazupon)
 * @license MIT
 */
+const i18nPluginId$1 = namespacedId("i18n");
 /**
 * Render the validation errors.
 *
-* @param _ctx - A {@link CommandContext | command context}
+* @param ctx - A {@link CommandContext | command context}
 * @param error - An {@link AggregateError} of option in `args-token` validation
 * @returns A rendered validation error.
 */
-function renderValidationErrors(_ctx, error) {
+async function renderValidationErrors(ctx, error) {
 	const messages = [];
-	for (const err of error.errors) messages.push(err.message);
-	return Promise.resolve(messages.join("\n"));
+	for (const err of error.errors) messages.push(await renderValidationError(ctx, err));
+	return messages.join("\n");
+}
+async function renderValidationError(ctx, error) {
+	if (isCommandNotFoundError(error) && error.code) {
+		const message = await localize(ctx, error.code, error.values);
+		if (message && message !== error.code) return message;
+	}
+	if (isArgsValidationError(error) && error.code) {
+		const values = await resolveValidationValues(ctx, error);
+		const message = await localize(ctx, error.code, values);
+		if (message && message !== error.code) return message;
+	}
+	return error.message;
+}
+async function resolveValidationValues(ctx, error) {
+	if (error.code !== ArgsValidationErrorKeys.customParse) return error.values;
+	const { reasonKey, reasonValues } = error.values;
+	if (typeof reasonKey !== "string") return error.values;
+	const key = resolveKey(reasonKey, ctx.name);
+	const localizedReason = await localize(ctx, key, toRecord(reasonValues));
+	if (!localizedReason || localizedReason === key) return error.values;
+	return {
+		...error.values,
+		reason: localizedReason
+	};
+}
+async function localize(ctx, key, values) {
+	const i18n = ctx.extensions?.[i18nPluginId$1];
+	if (i18n?.translate) return i18n.translate(key, values);
+	return key;
+}
+function toRecord(value) {
+	return value != null && typeof value === "object" ? value : Object.create(null);
 }
 //#endregion
 //#region ../plugin-renderer/src/index.ts

package/lib/{types-DZ0S_FSe.d.ts → types-CD5eRJFK.d.ts}

@@ -1,4 +1,4 @@
-import { i as Args, n as ArgSchema, o as ArgToken, r as ArgValues, t as ArgExplicitlyProvided } from "./resolver-mxPNDBm_.js";
+import { i as Args, n as ArgSchema, r as ArgValues, t as ArgExplicitlyProvided, u as ArgToken } from "./resolver-CgkhQ6Tt.js";
 
 //#region src/plugin/context.d.ts
 /**
@@ -529,6 +529,13 @@ interface CommandEnvironment<G extends GunshiParamsConstraint = DefaultGunshiPar
    * @see {@linkcode CliOptions.usageSilent}
    */
   usageSilent: boolean;
+  /**
+   * Whether to treat undefined options as argument validation errors.
+   *
+   * @default false
+   * @see {@linkcode CliOptions.strict}
+   */
+  strict: boolean;
   /**
    * Sub commands.
    *
@@ -616,6 +623,16 @@ interface CliOptions<G extends GunshiParamsConstraint = DefaultGunshiParams> {
    * Whether to display the command usage.
    */
   usageSilent?: boolean;
+  /**
+   * Whether to treat undefined options as argument validation errors.
+   *
+   * When enabled, option tokens that are not declared by the resolved command
+   * arguments or installed global options are reported as validation errors
+   * before the command runner is executed.
+   *
+   * @default false
+   */
+  strict?: boolean;
   /**
    * Render function the command usage.
    */

package/lib/utils-BKhsrjPW.js

@@ -0,0 +1,32 @@
+//#region ../../node_modules/.pnpm/args-tokens@0.28.0/node_modules/args-tokens/lib/utils.js
+/**
+* Entry point of utils.
+*
+* Note that this entry point is used by gunshi to import utility functions.
+*
+* @module
+*/
+/**
+* @author kazuya kawaguchi (a.k.a. kazupon)
+* @license MIT
+*/
+/**
+* Convert a string to kebab-case.
+*
+* @param str - A string to convert
+* @returns Converted string into kebab-case.
+*/
+function kebabnize(str) {
+	return str.replace(/[A-Z]/g, (match, offset) => (offset > 0 ? "-" : "") + match.toLowerCase());
+}
+/**
+* Format allowed argument choices for validation error values and fallback messages.
+*
+* @param choices - Choice values to format
+* @returns JSON-quoted choices joined with `, `.
+*/
+function formatChoices(choices) {
+	return choices.map((value) => JSON.stringify(value)).join(", ");
+}
+//#endregion
+export { kebabnize as n, formatChoices as t };

package/lib/utils.d.ts

@@ -1,6 +1,6 @@
-import { b as GunshiParamsConstraint, m as DefaultGunshiParams, p as Commandable, r as Command, x as LazyCommand } from "./types-DZ0S_FSe.js";
+import { b as GunshiParamsConstraint, m as DefaultGunshiParams, p as Commandable, r as Command, x as LazyCommand } from "./types-CD5eRJFK.js";
 
-//#region ../../node_modules/.pnpm/args-tokens@0.27.0/node_modules/args-tokens/lib/utils.d.ts
+//#region ../../node_modules/.pnpm/args-tokens@0.28.0/node_modules/args-tokens/lib/utils.d.ts
 
 //#region src/utils.d.ts
 /**
@@ -21,7 +21,12 @@ import { b as GunshiParamsConstraint, m as DefaultGunshiParams, p as Commandable
  * @returns Converted string into kebab-case.
  */
 declare function kebabnize(str: string): string;
-//#endregion
+/**
+ * Format allowed argument choices for validation error values and fallback messages.
+ *
+ * @param choices - Choice values to format
+ * @returns JSON-quoted choices joined with `, `.
+ */
 //#endregion
 //#region src/utils.d.ts
 /**

package/lib/utils.js

@@ -1,2 +1,110 @@
-import { a as log, i as isLazyCommand, n as deepFreeze, o as resolveLazyCommand, r as getCommandSubCommands, s as kebabnize, t as create } from "./utils-DNVHO9MQ.js";
+import { n as kebabnize } from "./utils-BKhsrjPW.js";
+//#region src/utils.ts
+/**
+* @author kazuya kawaguchi (a.k.a. kazupon)
+* @license MIT
+*/
+/**
+* Check if the given command is a {@link LazyCommand}.
+*
+* @param cmd - A command to check
+* @returns `true` if the command is a {@link LazyCommand}, otherwise `false
+*/
+function isLazyCommand(cmd) {
+	return typeof cmd === "function" && "commandName" in cmd && !!cmd.commandName;
+}
+/**
+* Resolve a lazy command to a {@link Command}.
+*
+* @param cmd - A {@link Commandable} or {@link LazyCommand} to resolve
+* @param name - Optional name of the command, if not provided, it will use the name from the command itself.
+* @param needRunResolving - Whether to run the resolving function of the lazy command.
+* @returns A resolved {@link Command}
+*/
+async function resolveLazyCommand(cmd, name, needRunResolving = false) {
+	let command;
+	if (isLazyCommand(cmd)) {
+		const baseCommand = {
+			name: cmd.commandName,
+			description: cmd.description,
+			args: cmd.args,
+			examples: cmd.examples,
+			internal: cmd.internal,
+			entry: cmd.entry,
+			subCommands: cmd.subCommands
+		};
+		if ("resource" in cmd && cmd.resource) baseCommand.resource = cmd.resource;
+		command = Object.assign(create(), baseCommand);
+		if (needRunResolving) {
+			const loaded = await cmd();
+			if (typeof loaded === "function") command.run = loaded;
+			else if (typeof loaded === "object") {
+				if (loaded.run == null) throw new TypeError(`'run' is required in command: ${cmd.name || name}`);
+				command.run = loaded.run;
+				command.name = loaded.name;
+				command.description = loaded.description;
+				command.args = loaded.args;
+				command.examples = loaded.examples;
+				command.internal = loaded.internal;
+				command.entry = loaded.entry;
+				command.subCommands = loaded.subCommands || cmd.subCommands;
+				if ("resource" in loaded && loaded.resource) command.resource = loaded.resource;
+			} else throw new TypeError(`Cannot resolve command: ${cmd.name || name}`);
+		}
+	} else command = Object.assign(create(), cmd);
+	if (command.name == null && name) command.name = name;
+	return deepFreeze(command);
+}
+/**
+* Create an object with the specified prototype. A shorthand for `Object.create`.
+*
+* @param obj - An object to use as the prototype for the new object. If `null`, it will create an object with no prototype.
+* @returns A new object with the specified prototype
+*/
+function create(obj = null) {
+	return Object.create(obj);
+}
+/**
+* Log a message to the console.
+*
+* @param args - Arguments to log
+*/
+function log(...args) {
+	console.log(...args);
+}
+/**
+* Get the sub-commands of a command as a normalized Map.
+*
+* @param cmd - A command or lazy command
+* @returns A Map of sub-commands, or undefined if the command has no sub-commands.
+*/
+function getCommandSubCommands(cmd) {
+	const subCommands = isLazyCommand(cmd) ? cmd.subCommands : typeof cmd === "object" ? cmd.subCommands : void 0;
+	if (!subCommands) return;
+	if (subCommands instanceof Map) return subCommands.size > 0 ? subCommands : void 0;
+	if (typeof subCommands === "object") {
+		const entries = Object.entries(subCommands);
+		if (entries.length === 0) return;
+		const map = /* @__PURE__ */ new Map();
+		for (const [name, cmd] of entries) map.set(name, cmd);
+		return map;
+	}
+}
+/**
+* Deep freeze an object, making it immutable.
+*
+* @param obj - The object to freeze
+* @param ignores - Properties to ignore during freezing
+* @returns A frozen object
+*/
+function deepFreeze(obj, ignores = []) {
+	if (obj === null || typeof obj !== "object") return obj;
+	for (const key of Object.keys(obj)) {
+		const value = obj[key];
+		if (ignores.includes(key)) continue;
+		if (typeof value === "object" && value !== null) deepFreeze(value, ignores);
+	}
+	return Object.freeze(obj);
+}
+//#endregion
 export { create, deepFreeze, getCommandSubCommands, isLazyCommand, kebabnize, log, resolveLazyCommand };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "gunshi",
   "description": "Modern javascript command-line library",
-  "version": "0.35.0",
+  "version": "0.35.2",
   "author": {
     "name": "kazuya kawaguchi",
     "email": "kawakazu80@gmail.com"
@@ -108,7 +108,7 @@
     }
   },
   "devDependencies": {
-    "args-tokens": "^0.27.0",
+    "args-tokens": "^0.28.0",
     "deno": "^2.7.14",
     "jsr": "^0.14.3",
     "jsr-exports-lint": "^0.4.2",
@@ -116,11 +116,11 @@
     "std-env": "^4.1.0",
     "tsdown": "0.21.0",
     "zod": "^4.4.3",
-    "@gunshi/plugin-i18n": "0.35.0",
-    "@gunshi/plugin-global": "0.35.0",
-    "@gunshi/plugin-renderer": "0.35.0",
-    "@gunshi/resources": "0.35.0",
-    "@gunshi/shared": "0.35.0"
+    "@gunshi/plugin-renderer": "0.35.2",
+    "@gunshi/plugin-i18n": "0.35.2",
+    "@gunshi/plugin-global": "0.35.2",
+    "@gunshi/resources": "0.35.2",
+    "@gunshi/shared": "0.35.2"
   },
   "scripts": {
     "build": "tsdown",

package/lib/constants-BkgP86Yw.d.ts

@@ -1,11 +0,0 @@
-import { m as DefaultGunshiParams, n as CliOptions } from "./types-DZ0S_FSe.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
-export { CLI_OPTIONS_DEFAULT as n, ANONYMOUS_COMMAND_NAME as t };

package/lib/constants-CQq1R_68.js

@@ -1,29 +0,0 @@
-//#region src/constants.ts
-/**
-* @author kazuya kawaguchi (a.k.a. kazupon)
-* @license MIT
-*/
-const ANONYMOUS_COMMAND_NAME = "(anonymous)";
-/**
-* A no-operation function.
-*/
-const NOOP = () => {};
-const CLI_OPTIONS_DEFAULT = {
-	name: void 0,
-	description: void 0,
-	version: void 0,
-	cwd: void 0,
-	usageSilent: false,
-	subCommands: void 0,
-	leftMargin: 2,
-	middleMargin: 10,
-	usageOptionType: false,
-	usageOptionValue: true,
-	renderHeader: void 0,
-	renderUsage: void 0,
-	renderValidationErrors: void 0,
-	plugins: void 0,
-	fallbackToEntry: false
-};
-//#endregion
-export { CLI_OPTIONS_DEFAULT as n, NOOP as r, ANONYMOUS_COMMAND_NAME as t };

package/lib/utils-DNVHO9MQ.js

@@ -1,131 +0,0 @@
-//#region ../../node_modules/.pnpm/args-tokens@0.27.0/node_modules/args-tokens/lib/utils.js
-/**
-* Entry point of utils.
-*
-* Note that this entry point is used by gunshi to import utility functions.
-*
-* @module
-*/
-/**
-* @author kazuya kawaguchi (a.k.a. kazupon)
-* @license MIT
-*/
-/**
-* Convert a string to kebab-case.
-*
-* @param str - A string to convert
-* @returns Converted string into kebab-case.
-*/
-function kebabnize(str) {
-	return str.replace(/[A-Z]/g, (match, offset) => (offset > 0 ? "-" : "") + match.toLowerCase());
-}
-//#endregion
-//#region src/utils.ts
-/**
-* @author kazuya kawaguchi (a.k.a. kazupon)
-* @license MIT
-*/
-/**
-* Check if the given command is a {@link LazyCommand}.
-*
-* @param cmd - A command to check
-* @returns `true` if the command is a {@link LazyCommand}, otherwise `false
-*/
-function isLazyCommand(cmd) {
-	return typeof cmd === "function" && "commandName" in cmd && !!cmd.commandName;
-}
-/**
-* Resolve a lazy command to a {@link Command}.
-*
-* @param cmd - A {@link Commandable} or {@link LazyCommand} to resolve
-* @param name - Optional name of the command, if not provided, it will use the name from the command itself.
-* @param needRunResolving - Whether to run the resolving function of the lazy command.
-* @returns A resolved {@link Command}
-*/
-async function resolveLazyCommand(cmd, name, needRunResolving = false) {
-	let command;
-	if (isLazyCommand(cmd)) {
-		const baseCommand = {
-			name: cmd.commandName,
-			description: cmd.description,
-			args: cmd.args,
-			examples: cmd.examples,
-			internal: cmd.internal,
-			entry: cmd.entry,
-			subCommands: cmd.subCommands
-		};
-		if ("resource" in cmd && cmd.resource) baseCommand.resource = cmd.resource;
-		command = Object.assign(create(), baseCommand);
-		if (needRunResolving) {
-			const loaded = await cmd();
-			if (typeof loaded === "function") command.run = loaded;
-			else if (typeof loaded === "object") {
-				if (loaded.run == null) throw new TypeError(`'run' is required in command: ${cmd.name || name}`);
-				command.run = loaded.run;
-				command.name = loaded.name;
-				command.description = loaded.description;
-				command.args = loaded.args;
-				command.examples = loaded.examples;
-				command.internal = loaded.internal;
-				command.entry = loaded.entry;
-				command.subCommands = loaded.subCommands || cmd.subCommands;
-				if ("resource" in loaded && loaded.resource) command.resource = loaded.resource;
-			} else throw new TypeError(`Cannot resolve command: ${cmd.name || name}`);
-		}
-	} else command = Object.assign(create(), cmd);
-	if (command.name == null && name) command.name = name;
-	return deepFreeze(command);
-}
-/**
-* Create an object with the specified prototype. A shorthand for `Object.create`.
-*
-* @param obj - An object to use as the prototype for the new object. If `null`, it will create an object with no prototype.
-* @returns A new object with the specified prototype
-*/
-function create(obj = null) {
-	return Object.create(obj);
-}
-/**
-* Log a message to the console.
-*
-* @param args - Arguments to log
-*/
-function log(...args) {
-	console.log(...args);
-}
-/**
-* Get the sub-commands of a command as a normalized Map.
-*
-* @param cmd - A command or lazy command
-* @returns A Map of sub-commands, or undefined if the command has no sub-commands.
-*/
-function getCommandSubCommands(cmd) {
-	const subCommands = isLazyCommand(cmd) ? cmd.subCommands : typeof cmd === "object" ? cmd.subCommands : void 0;
-	if (!subCommands) return;
-	if (subCommands instanceof Map) return subCommands.size > 0 ? subCommands : void 0;
-	if (typeof subCommands === "object") {
-		const entries = Object.entries(subCommands);
-		if (entries.length === 0) return;
-		const map = /* @__PURE__ */ new Map();
-		for (const [name, cmd] of entries) map.set(name, cmd);
-		return map;
-	}
-}
-/**
-* Deep freeze an object, making it immutable.
-*
-* @param obj - The object to freeze
-* @param ignores - Properties to ignore during freezing
-* @returns A frozen object
-*/
-function deepFreeze(obj, ignores = []) {
-	if (obj === null || typeof obj !== "object") return obj;
-	for (const key of Object.keys(obj)) {
-		const value = obj[key];
-		if (ignores.includes(key)) continue;
-		if (typeof value === "object" && value !== null) deepFreeze(value, ignores);
-	}
-	return Object.freeze(obj);
-}
-//#endregion
-export { log as a, isLazyCommand as i, deepFreeze as n, resolveLazyCommand as o, getCommandSubCommands as r, kebabnize as s, create as t };