gunshi 1.0.0-beta.2 → 1.0.0-rc.2

package/lib/agent.d.ts

@@ -1,9 +1,8 @@
-//#region ../../node_modules/.pnpm/std-env@4.1.0/node_modules/std-env/dist/index.d.mts
-//#region src/agents.d.ts
+//#region ../../node_modules/.pnpm/std-env@4.2.0/node_modules/std-env/dist/index.d.mts
 /**
  * Represents the name of an AI coding agent.
  */
-type AgentName = (string & {}) | "cursor" | "claude" | "devin" | "replit" | "gemini" | "codex" | "auggie" | "opencode" | "kiro" | "goose" | "pi";
+type AgentName = (string & {}) | "cursor" | "claude" | "devin" | "replit" | "gemini" | "codex" | "auggie" | "opencode" | "kiro" | "goose" | "pi" | "junie";
 //#endregion
 //#region src/agent.d.ts
 /**

package/lib/agent.js

@@ -1,4 +1,4 @@
-//#region ../../node_modules/.pnpm/std-env@4.1.0/node_modules/std-env/dist/index.mjs
+//#region ../../node_modules/.pnpm/std-env@4.2.0/node_modules/std-env/dist/index.mjs
 const e = globalThis.process?.env || Object.create(null);
 const t = globalThis.process || { env: e };
 const n = t !== void 0 && t.env && t.env.NODE_ENV || void 0;
@@ -11,14 +11,16 @@ const r = [
 	[`pi`, [i(`PATH`, /\.pi[\\/]agent/)]],
 	[`auggie`, [`AUGMENT_AGENT`]],
 	[`goose`, [`GOOSE_PROVIDER`]],
+	[`junie`, [`JUNIE_DATA`, `JUNIE_SHIM_PATH`]],
 	[`devin`, [i(`EDITOR`, /devin/)]],
 	[`cursor`, [`CURSOR_AGENT`]],
-	[`kiro`, [i(`TERM_PROGRAM`, /kiro/)]]
+	[`kiro`, [i(`TERM_PROGRAM`, /kiro/, { noTTY: !0 })]]
 ];
-function i(t, n) {
+function i(n, r, i) {
 	return () => {
-		let r = e[t];
-		return r ? n.test(r) : !1;
+		if (i?.noTTY && t.stdout?.isTTY) return !1;
+		let a = e[n];
+		return a ? r.test(a) : !1;
 	};
 }
 function a() {

package/lib/bone.d.ts

@@ -1,5 +1,5 @@
-import { i as Args, l as ArgToken, n as ArgSchema, r as ArgValues } from "./resolver-BezrTUr7.js";
-import { C as NormalizeToGunshiParams, D as SubCommandable, E as RenderingOptions, O as ValidationErrorsDecorator, S as MergeGunshiExtensions, T as RendererDecorator, _ as ExtractArgs, a as CommandContext, b as GunshiParamsConstraint, c as CommandDecorator, d as CommandLoader, f as CommandRunner, g as ExtractArgExplicitlyProvided, h as ExtendContext, i as CommandCallMode, l as CommandEnvironment, m as DefaultGunshiParams, n as CliOptions, o as CommandContextCore, p as Commandable, r as Command, s as CommandContextExtension, t as Awaitable, u as CommandExamplesFetcher, v as ExtractExtensions, w as Prettify, x as LazyCommand, y as GunshiParams } from "./types-lD5uzpd5.js";
+import { i as Args, l as ArgToken, n as ArgSchema, r as ArgValues } from "./resolver-Cbtx2IyH.js";
+import { C as NormalizeToGunshiParams, D as SubCommandable, E as RenderingOptions, O as ValidationErrorsDecorator, S as MergeGunshiExtensions, T as RendererDecorator, _ as ExtractArgs, a as CommandContext, b as GunshiParamsConstraint, c as CommandDecorator, d as CommandLoader, f as CommandRunner, g as ExtractArgExplicitlyProvided, h as ExtendContext, i as CommandCallMode, l as CommandEnvironment, m as DefaultGunshiParams, n as CliOptions, o as CommandContextCore, p as Commandable, r as Command, s as CommandContextExtension, t as Awaitable, u as CommandExamplesFetcher, v as ExtractExtensions, w as Prettify, x as LazyCommand, y as GunshiParams } from "./types-jrddQ_Kw.js";
 //#region src/cli/bone.d.ts
 /**
  * Run the command.

package/lib/bone.js

@@ -1,4 +1,4 @@
-import { t as cliCore } from "./core-D9EEP3Ac.js";
+import { t as cliCore } from "./core-CrrcHkyV.js";
 //#region src/cli/bone.ts
 /**
 * @author kazuya kawaguchi (a.k.a. kazupon)

package/lib/{builtin-ClJbNR1q.js → builtin-C4T7jgn7.js}

@@ -1,7 +1,7 @@
-import { a as hasPriorityValidationError } from "./error-wB83kWiv.js";
-import { t as plugin } from "./plugin-CG94VzCl.js";
-import { a as namespacedId, o as COMMON_ARGS, t as renderer } from "./src-Dr9mmkFc.js";
-import { t as cliCore } from "./core-D9EEP3Ac.js";
+import { a as hasPriorityValidationError } from "./error-pbHb3QAL.js";
+import { t as plugin } from "./plugin-Fea3gCnT.js";
+import { a as namespacedId, o as COMMON_ARGS, t as renderer } from "./src-0zuC_LJU.js";
+import { t as cliCore } from "./core-CrrcHkyV.js";
 //#region ../plugin-global/src/types.ts
 /**
 * @author kazuya kawaguchi (a.k.a. kazupon)
@@ -18,6 +18,36 @@ const pluginId = namespacedId("global");
 * @license MIT
 */
 /**
+* The key of the registry in which the core keeps, for the command context of each run, the set of the
+* errors that have been reported to the user. An error in the set tells `cli()` to end without
+* rejecting. The errors are frozen with the command context, so they are not marked themselves. The key
+* is a registered symbol, since `gunshi` and the plugins bundle their own copies.
+*/
+const REPORTED = Symbol.for("gunshi.reported");
+/**
+* Mark an error as reported to the user, in the set that the core keeps for the run of the context.
+*
+* @param ctx - The command context of the run
+* @param error - The error that has been reported
+* @returns `true` if the error is marked, `false` if the core keeps no set for the run
+*/
+function markReported(ctx, error) {
+	const reported = globalThis[REPORTED]?.get(ctx);
+	if (reported === void 0) return false;
+	reported.add(error);
+	return true;
+}
+/**
+* Set the exit code of the process, where the runtime has one (Node.js, Bun and Deno 2 have `process`).
+* The core does not call the APIs of a runtime, so the plugin, which reports the errors, sets it.
+*
+* @param code - The exit code
+*/
+function setExitCode(code) {
+	const proc = globalThis.process;
+	if (proc != null && typeof proc === "object") proc.exitCode = code;
+}
+/**
 * Decorator function to extend the command with global options.
 *
 * @param baseRunner - The base command runner
@@ -29,27 +59,25 @@ const decorator = (baseRunner) => async (ctx) => {
 	* declares the same name — even with an identical schema — is not in that map, so `--version` /
 	* `--help` belong to the command.
 	*/
-	const { values, validationError, env: { globalOptions }, extensions: { [pluginId]: { showVersion, showHeader, showUsage, showValidationErrors } } } = ctx;
-	if (hasPriorityValidationError(validationError)) {
-		await showValidationErrors(validationError);
-		throw validationError;
-	}
+	const { values, validationError, env: { globalOptions }, extensions: { [pluginId]: { showVersion, showUsage, showValidationErrors } } } = ctx;
+	/**
+	* NOTE(kazupon): when the plugin has shown the validation errors to the user, they have been
+	* reported: the exit code is 1, and `cli()` ends without rejecting, as the other CLI libraries end
+	* without a stack trace. They are still thrown, so that the `onErrorCommand` hook sees them. When
+	* nothing was shown (`renderValidationErrors: null`, an empty message, or `usageSilent`), `cli()`
+	* rejects with them, for the app to report them. So it does when the core keeps no set of reported
+	* errors for the run, and then the exit code is left alone.
+	*
+	* @param error - The aggregate error of the validation errors
+	*/
+	const report = async (error) => {
+		if (await showValidationErrors(error) && !ctx.env.usageSilent && markReported(ctx, error)) setExitCode(1);
+		throw error;
+	};
+	if (hasPriorityValidationError(validationError)) return await report(validationError);
 	if (values.version && globalOptions?.has("version")) return showVersion();
-	const buf = [];
-	const header = await showHeader();
-	if (header) buf.push(header);
-	if (values.help && globalOptions?.has("help")) {
-		const usage = await showUsage();
-		if (usage) {
-			buf.push(usage);
-			return buf.join("\n");
-		}
-		return;
-	}
-	if (validationError) {
-		await showValidationErrors(validationError);
-		throw validationError;
-	}
+	if (values.help && globalOptions?.has("help")) return await showUsage();
+	if (validationError) return await report(validationError);
 	return baseRunner(ctx);
 };
 //#endregion
@@ -83,19 +111,31 @@ function extension(ctx) {
 			return header;
 		},
 		showUsage: async () => {
-			if (ctx.env.renderUsage != null) {
-				const usage = await ctx.env.renderUsage(ctx);
-				if (usage) {
-					ctx.log(usage);
-					return usage;
-				}
+			if (ctx.env.renderUsage == null) return;
+			const usage = await ctx.env.renderUsage(ctx);
+			if (!usage) return;
+			/**
+			* NOTE(kazupon): the header is the title of the usage, so it comes with the usage, wherever the
+			* usage is shown: for `--help`, and when a command that takes `--help` itself shows it. It is not
+			* shown before a command runs, where it would come before what the command prints, such as JSON.
+			*/
+			const header = ctx.env.renderHeader == null ? void 0 : await ctx.env.renderHeader(ctx);
+			if (header) {
+				ctx.log(header);
+				ctx.log();
 			}
+			ctx.log(usage);
+			return header ? [header, usage].join("\n") : usage;
 		},
 		showValidationErrors: async (error) => {
 			if (ctx.env.renderValidationErrors === null) return;
 			if (ctx.env.renderValidationErrors !== void 0) {
 				const message = await ctx.env.renderValidationErrors(ctx, error);
-				ctx.log(message);
+				/**
+				* NOTE(kazupon): the validation errors are diagnostics, not the output of the command, so they
+				* go to stderr, as the other CLI libraries do. stdout stays for what a command prints, such as JSON.
+				*/
+				if (message && !ctx.env.usageSilent) console.error(message);
 				return message;
 			}
 		}
@@ -163,6 +203,7 @@ function global() {
 * @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}
 * @returns A rendered usage or undefined. if you will use {@linkcode CliOptions.usageSilent} option, it will return rendered usage string.
+* It is also `undefined` when the arguments fail validation and the errors are reported to stderr (see {@linkcode CliOptions.renderValidationErrors}).
 */
 async function cli(args, entry, options = {}) {
 	return cliCore(args, entry, options, createBuiltInPlugins());

package/lib/combinators.d.ts

@@ -1,5 +1,5 @@
-import { i as Args, n as ArgSchema } from "./resolver-BezrTUr7.js";
-//#region ../../node_modules/.pnpm/args-tokens@1.0.0-beta.1/node_modules/args-tokens/lib/combinators.d.ts
+import { i as Args, n as ArgSchema } from "./resolver-Cbtx2IyH.js";
+//#region ../../node_modules/.pnpm/args-tokens@1.0.0/node_modules/args-tokens/lib/combinators.d.ts
 //#region src/combinators.d.ts
 /**
  * A combinator produced by combinator factory functions.

package/lib/combinators.js

@@ -1,6 +1,6 @@
-import { t as formatChoices } from "./utils-CJLgPw25.js";
-import { n as ArgsValidationErrorKeys, r as PURE_PARSE, t as ArgsValidationError } from "./resolver-CAlgxe_R-y4BytVTg.js";
-//#region ../../node_modules/.pnpm/args-tokens@1.0.0-beta.1/node_modules/args-tokens/lib/combinators.js
+import { t as formatChoices } from "./utils-D-MmF6sM.js";
+import { n as ArgsValidationErrorKeys, r as PURE_PARSE, t as ArgsValidationError } from "./resolver-CAlgxe_R-3pz9PVFu.js";
+//#region ../../node_modules/.pnpm/args-tokens@1.0.0/node_modules/args-tokens/lib/combinators.js
 /**
 * Parser combinator factory functions for composable argument schema construction.
 *

package/lib/context.d.ts

@@ -1,5 +1,5 @@
-import { i as Args, l as ArgToken, r as ArgValues } from "./resolver-BezrTUr7.js";
-import { _ as ExtractArgs, a as CommandContext, b as GunshiParamsConstraint, g as ExtractArgExplicitlyProvided, h as ExtendContext, i as CommandCallMode, m as DefaultGunshiParams, n as CliOptions, r as Command, s as CommandContextExtension, x as LazyCommand, y as GunshiParams } from "./types-lD5uzpd5.js";
+import { i as Args, l as ArgToken, r as ArgValues } from "./resolver-Cbtx2IyH.js";
+import { _ as ExtractArgs, a as CommandContext, b as GunshiParamsConstraint, g as ExtractArgExplicitlyProvided, h as ExtendContext, i as CommandCallMode, m as DefaultGunshiParams, n as CliOptions, r as Command, s as CommandContextExtension, x as LazyCommand, y as GunshiParams } from "./types-jrddQ_Kw.js";
 //#region src/context.d.ts
 /**
  * Extract extension return types from extensions record

package/lib/{core-D9EEP3Ac.js → core-CrrcHkyV.js}

@@ -1,8 +1,8 @@
 import { i as NOOP, r as CLI_OPTIONS_DEFAULT, t as createCommandContext } from "./context-CSecf6R5.js";
-import { n as kebabnize } from "./utils-CJLgPw25.js";
+import { n as kebabnize } from "./utils-D-MmF6sM.js";
 import { create, getCommandSubCommands, isLazyCommand, resolveLazyCommand } from "./utils.js";
-import { a as resolveArgs, n as ArgsValidationErrorKeys, o as parseArgs, t as ArgsValidationError } from "./resolver-CAlgxe_R-y4BytVTg.js";
-import { a as hasPriorityValidationError, i as CommandResolutionErrorKeys, n as CommandNotFoundErrorKeys, r as CommandResolutionError, t as CommandNotFoundError } from "./error-wB83kWiv.js";
+import { a as resolveArgs, n as ArgsValidationErrorKeys, o as parseArgs, t as ArgsValidationError } from "./resolver-CAlgxe_R-3pz9PVFu.js";
+import { a as hasPriorityValidationError, i as CommandResolutionErrorKeys, n as CommandNotFoundErrorKeys, r as CommandResolutionError, t as CommandNotFoundError } from "./error-pbHb3QAL.js";
 //#region src/decorators.ts
 /**
 * @author kazuya kawaguchi (a.k.a. kazupon)
@@ -324,7 +324,7 @@ async function cliCore(argv, entry, options, plugins, usageOnly = false) {
 		skipPositional
 	});
 	const validationError = mergeValidationErrors(error, [...additionalValidationErrors, ...cliOptions.strict && !diagnostic ? createUnknownOptionErrors(findUnknownOptions(args, tokens, { toKebab: resolvedCommand.toKebab })) : []]);
-	return await executeCommand(resolvedCommand, await createCommandContext({
+	const commandContext = await createCommandContext({
 		args,
 		explicit,
 		values,
@@ -339,7 +339,41 @@ async function cliCore(argv, entry, options, plugins, usageOnly = false) {
 		extensions: getPluginExtensions(resolvedPlugins),
 		validationError,
 		cliOptions
-	}), decorators.commandDecorators);
+	});
+	const reported = trackReported(commandContext);
+	try {
+		return await executeCommand(resolvedCommand, commandContext, decorators.commandDecorators);
+	} catch (error) {
+		/**
+		* NOTE(kazupon): a plugin that has reported the validation errors to the user marks them, as the
+		* global options plugin does after it prints them to stderr and sets the exit code. They have been
+		* dealt with, and `onErrorCommand` has seen them in `executeCommand`, so `cli()` ends without
+		* rejecting. Errors that nobody reported, such as when the app renders the validation errors itself
+		* or an error thrown by a command, reject as before.
+		*/
+		if (error != null && typeof error === "object" && reported.has(error)) return;
+		throw error;
+	}
+}
+/**
+* The key of the registry that maps the command context of a run to the set of the errors that a plugin
+* has reported to the user during the run. The global options plugin uses the same registered symbol,
+* since `gunshi` and the plugins bundle their own copies.
+*/
+const REPORTED = Symbol.for("gunshi.reported");
+/**
+* Prepare the set of the errors that a plugin reports to the user during a run. The set belongs to the
+* command context of the run, so a report counts for this run only: not for a nested `cli()` in a hook,
+* nor for a later run in which the same error is thrown again.
+*
+* @param ctx - The command context of the run
+* @returns The set of the errors that have been reported during the run
+*/
+function trackReported(ctx) {
+	const registry = globalThis;
+	const reported = /* @__PURE__ */ new WeakSet();
+	(registry[REPORTED] ??= /* @__PURE__ */ new WeakMap()).set(ctx, reported);
+	return reported;
 }
 /**
 * Create the decorator that renders the usage of the command instead of running it.

package/lib/definition.d.ts

@@ -1,5 +1,5 @@
-import { i as Args, n as ArgSchema, r as ArgValues } from "./resolver-BezrTUr7.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-lD5uzpd5.js";
+import { i as Args, n as ArgSchema, r as ArgValues } from "./resolver-Cbtx2IyH.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-jrddQ_Kw.js";
 import { CommandContextParams, createCommandContext } from "./context.js";
 //#region src/definition.d.ts
 /**

package/lib/{error-e_--t4mB.d.ts → error-DgUj3WPU.d.ts}

@@ -1,5 +1,5 @@
-import { a as ArgsValidationError } from "./resolver-BezrTUr7.js";
-import { m as DefaultGunshiParams, n as CliOptions } from "./types-lD5uzpd5.js";
+import { a as ArgsValidationError } from "./resolver-Cbtx2IyH.js";
+import { m as DefaultGunshiParams, n as CliOptions } from "./types-jrddQ_Kw.js";
 //#region src/constants.d.ts
 declare const ANONYMOUS_COMMAND_NAME = "(anonymous)";
 declare const CLI_OPTIONS_DEFAULT: CliOptions<DefaultGunshiParams>;

package/lib/{error-wB83kWiv.js → error-pbHb3QAL.js}

@@ -1,5 +1,5 @@
-import { i as isArgsValidationError$1, n as ArgsValidationErrorKeys, t as ArgsValidationError } from "./resolver-CAlgxe_R-y4BytVTg.js";
-//#region ../../node_modules/.pnpm/args-tokens@1.0.0-beta.1/node_modules/args-tokens/lib/index.js
+import { i as isArgsValidationError$1, n as ArgsValidationErrorKeys, t as ArgsValidationError } from "./resolver-CAlgxe_R-3pz9PVFu.js";
+//#region ../../node_modules/.pnpm/args-tokens@1.0.0/node_modules/args-tokens/lib/index.js
 /**
 * @author kazuya kawaguchi (a.k.a. kazupon)
 * @license MIT

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-lD5uzpd5.js";
+import { b as GunshiParamsConstraint, m as DefaultGunshiParams, n as CliOptions, r as Command, x as LazyCommand } from "./types-jrddQ_Kw.js";
 //#region src/generator.d.ts
 /**
  * generate options of `generate` function.

package/lib/generator.js

@@ -1,5 +1,5 @@
 import { create } from "./utils.js";
-import { n as cliUsage } from "./builtin-ClJbNR1q.js";
+import { n as cliUsage } from "./builtin-C4T7jgn7.js";
 //#region src/generator.ts
 /**
 * The entry for usage generator.

package/lib/index.d.ts

@@ -1,8 +1,8 @@
-import { a as ArgsValidationError, c as resolveArgs, i as Args, l as ArgToken, n as ArgSchema, o as ArgsValidationErrorCode, r as ArgValues, s as ArgsValidationErrorKeys, u as parseArgs } from "./resolver-BezrTUr7.js";
-import { A as Plugin, C as NormalizeToGunshiParams, D as SubCommandable, E as RenderingOptions, F as PluginWithExtension, I as PluginWithoutExtension, L as plugin, M as PluginExtension, N as PluginFunction, O as ValidationErrorsDecorator, P as PluginOptions, R as PluginContext, S as MergeGunshiExtensions, T as RendererDecorator, _ as ExtractArgs, a as CommandContext, b as GunshiParamsConstraint, c as CommandDecorator, d as CommandLoader, f as CommandRunner, g as ExtractArgExplicitlyProvided, h as ExtendContext, i as CommandCallMode, j as PluginDependency, k as OnPluginExtension, l as CommandEnvironment, m as DefaultGunshiParams, n as CliOptions, o as CommandContextCore, p as Commandable, r as Command, s as CommandContextExtension, t as Awaitable, u as CommandExamplesFetcher, v as ExtractExtensions, w as Prettify, x as LazyCommand, y as GunshiParams } from "./types-lD5uzpd5.js";
+import { a as ArgsValidationError, c as resolveArgs, i as Args, l as ArgToken, n as ArgSchema, o as ArgsValidationErrorCode, r as ArgValues, s as ArgsValidationErrorKeys, u as parseArgs } from "./resolver-Cbtx2IyH.js";
+import { A as Plugin, C as NormalizeToGunshiParams, D as SubCommandable, E as RenderingOptions, F as PluginWithExtension, I as PluginWithoutExtension, L as plugin, M as PluginExtension, N as PluginFunction, O as ValidationErrorsDecorator, P as PluginOptions, R as PluginContext, S as MergeGunshiExtensions, T as RendererDecorator, _ as ExtractArgs, a as CommandContext, b as GunshiParamsConstraint, c as CommandDecorator, d as CommandLoader, f as CommandRunner, g as ExtractArgExplicitlyProvided, h as ExtendContext, i as CommandCallMode, j as PluginDependency, k as OnPluginExtension, l as CommandEnvironment, m as DefaultGunshiParams, n as CliOptions, o as CommandContextCore, p as Commandable, r as Command, s as CommandContextExtension, t as Awaitable, u as CommandExamplesFetcher, v as ExtractExtensions, w as Prettify, x as LazyCommand, y as GunshiParams } from "./types-jrddQ_Kw.js";
 import { CommandContextParams, createCommandContext } from "./context.js";
 import { define, defineWithTypes, lazy, lazyWithTypes } from "./definition.js";
-import { a as CommandResolutionError, c as CommandResolutionErrorOptions, d as isCommandNotFoundError, f as isCommandResolutionError, i as CommandNotFoundErrorOptions, l as hasPriorityValidationError, n as CommandNotFoundErrorCode, o as CommandResolutionErrorCode, p as ANONYMOUS_COMMAND_NAME, r as CommandNotFoundErrorKeys, s as CommandResolutionErrorKeys, t as CommandNotFoundError, u as isArgsValidationError } from "./error-e_--t4mB.js";
+import { a as CommandResolutionError, c as CommandResolutionErrorOptions, d as isCommandNotFoundError, f as isCommandResolutionError, i as CommandNotFoundErrorOptions, l as hasPriorityValidationError, n as CommandNotFoundErrorCode, o as CommandResolutionErrorCode, p as ANONYMOUS_COMMAND_NAME, r as CommandNotFoundErrorKeys, s as CommandResolutionErrorKeys, t as CommandNotFoundError, u as isArgsValidationError } from "./error-DgUj3WPU.js";
 //#region ../plugin-i18n/src/types.d.ts
 /**
  * Translation adapter factory options.
@@ -114,6 +114,7 @@ declare class DefaultTranslation implements TranslationAdapter {
  * @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}
  * @returns A rendered usage or undefined. if you will use {@linkcode CliOptions.usageSilent} option, it will return rendered usage string.
+ * It is also `undefined` when the arguments fail validation and the errors are reported to stderr (see {@linkcode CliOptions.renderValidationErrors}).
  */
 declare function cli<G extends GunshiParamsConstraint>(args: string[], entry: Command<G> | CommandRunner<G> | LazyCommand<G>, options?: CliOptions<G>): Promise<string | undefined>;
 /**
@@ -125,6 +126,7 @@ declare function cli<G extends GunshiParamsConstraint>(args: string[], entry: Co
  * @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}
  * @returns A rendered usage or undefined. if you will use {@linkcode CliOptions.usageSilent} option, it will return rendered usage string.
+ * It is also `undefined` when the arguments fail validation and the errors are reported to stderr (see {@linkcode CliOptions.renderValidationErrors}).
  */
 declare function cli<A extends Args = Args, G extends GunshiParams = {
   args: A;
@@ -139,6 +141,7 @@ declare function cli<A extends Args = Args, G extends GunshiParams = {
  * @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}
  * @returns A rendered usage or undefined. if you will use {@linkcode CliOptions.usageSilent} option, it will return rendered usage string.
+ * It is also `undefined` when the arguments fail validation and the errors are reported to stderr (see {@linkcode CliOptions.renderValidationErrors}).
  */
 declare function cli<E extends ExtendContext = ExtendContext, G extends GunshiParams = {
   args: Args;
@@ -153,6 +156,7 @@ declare function cli<E extends ExtendContext = ExtendContext, G extends GunshiPa
  * @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}
  * @returns A rendered usage or undefined. if you will use {@linkcode CliOptions.usageSilent} option, it will return rendered usage string.
+ * It is also `undefined` when the arguments fail validation and the errors are reported to stderr (see {@linkcode CliOptions.renderValidationErrors}).
  */
 declare function cli<G extends GunshiParams = DefaultGunshiParams>(args: string[], entry: Command<G> | CommandRunner<G> | LazyCommand<G>, options?: CliOptions<G>): Promise<string | undefined>;
 /**
@@ -170,6 +174,7 @@ declare function cli<G extends GunshiParams = DefaultGunshiParams>(args: string[
  * @param entry - A command-like object (command, command runner, or lazy command)
  * @param options - A {@link CliOptions | CLI options}
  * @returns A rendered usage or undefined. if you will use {@linkcode CliOptions.usageSilent} option, it will return rendered usage string.
+ * It is also `undefined` when the arguments fail validation and the errors are reported to stderr (see {@linkcode CliOptions.renderValidationErrors}).
  */
 declare function cli(args: string[], entry: SubCommandable, options?: CliOptions): Promise<string | undefined>;
 //#endregion

package/lib/index.js

@@ -1,9 +1,9 @@
 import { n as ANONYMOUS_COMMAND_NAME, t as createCommandContext } from "./context-CSecf6R5.js";
-import { a as resolveArgs, n as ArgsValidationErrorKeys, o as parseArgs, t as ArgsValidationError } from "./resolver-CAlgxe_R-y4BytVTg.js";
-import { a as hasPriorityValidationError, c as isCommandResolutionError, i as CommandResolutionErrorKeys, n as CommandNotFoundErrorKeys, o as isArgsValidationError, r as CommandResolutionError, s as isCommandNotFoundError, t as CommandNotFoundError } from "./error-wB83kWiv.js";
-import { t as plugin } from "./plugin-CG94VzCl.js";
-import { a as namespacedId } from "./src-Dr9mmkFc.js";
-import { t as cli } from "./builtin-ClJbNR1q.js";
+import { a as resolveArgs, n as ArgsValidationErrorKeys, o as parseArgs, t as ArgsValidationError } from "./resolver-CAlgxe_R-3pz9PVFu.js";
+import { a as hasPriorityValidationError, c as isCommandResolutionError, i as CommandResolutionErrorKeys, n as CommandNotFoundErrorKeys, o as isArgsValidationError, r as CommandResolutionError, s as isCommandNotFoundError, t as CommandNotFoundError } from "./error-pbHb3QAL.js";
+import { t as plugin } from "./plugin-Fea3gCnT.js";
+import { a as namespacedId } from "./src-0zuC_LJU.js";
+import { t as cli } from "./builtin-C4T7jgn7.js";
 import { define, defineWithTypes, lazy, lazyWithTypes } from "./definition.js";
 //#region ../plugin-i18n/src/translation.ts
 /**

package/lib/{plugin-CG94VzCl.js → plugin-Fea3gCnT.js}

@@ -1,4 +1,4 @@
-import "./error-wB83kWiv.js";
+import "./error-pbHb3QAL.js";
 //#region src/plugin/core.ts
 /**
 * @author kazuya kawaguchi (a.k.a. kazupon)

package/lib/plugin.d.ts

@@ -1,5 +1,5 @@
-import { a as ArgsValidationError, i as Args, l as ArgToken, n as ArgSchema, o as ArgsValidationErrorCode, r as ArgValues, s as ArgsValidationErrorKeys } from "./resolver-BezrTUr7.js";
-import { A as Plugin, C as NormalizeToGunshiParams, F as PluginWithExtension, I as PluginWithoutExtension, L as plugin, M as PluginExtension, N as PluginFunction, O as ValidationErrorsDecorator, P as PluginOptions, R as PluginContext, S as MergeGunshiExtensions, T as RendererDecorator, _ as ExtractArgs, a as CommandContext, b as GunshiParamsConstraint, c as CommandDecorator, f as CommandRunner, h as ExtendContext, j as PluginDependency, k as OnPluginExtension, m as DefaultGunshiParams, o as CommandContextCore, r as Command, s as CommandContextExtension, t as Awaitable, u as CommandExamplesFetcher, v as ExtractExtensions, w as Prettify, x as LazyCommand, y as GunshiParams } from "./types-lD5uzpd5.js";
+import { a as ArgsValidationError, i as Args, l as ArgToken, n as ArgSchema, o as ArgsValidationErrorCode, r as ArgValues, s as ArgsValidationErrorKeys } from "./resolver-Cbtx2IyH.js";
+import { A as Plugin, C as NormalizeToGunshiParams, F as PluginWithExtension, I as PluginWithoutExtension, L as plugin, M as PluginExtension, N as PluginFunction, O as ValidationErrorsDecorator, P as PluginOptions, R as PluginContext, S as MergeGunshiExtensions, T as RendererDecorator, _ as ExtractArgs, a as CommandContext, b as GunshiParamsConstraint, c as CommandDecorator, f as CommandRunner, h as ExtendContext, j as PluginDependency, k as OnPluginExtension, m as DefaultGunshiParams, o as CommandContextCore, r as Command, s as CommandContextExtension, t as Awaitable, u as CommandExamplesFetcher, v as ExtractExtensions, w as Prettify, x as LazyCommand, y as GunshiParams } from "./types-jrddQ_Kw.js";
 import { CommandContextParams, createCommandContext } from "./context.js";
-import { a as CommandResolutionError, c as CommandResolutionErrorOptions, d as isCommandNotFoundError, f as isCommandResolutionError, i as CommandNotFoundErrorOptions, l as hasPriorityValidationError, m as CLI_OPTIONS_DEFAULT, n as CommandNotFoundErrorCode, o as CommandResolutionErrorCode, p as ANONYMOUS_COMMAND_NAME, r as CommandNotFoundErrorKeys, s as CommandResolutionErrorKeys, t as CommandNotFoundError, u as isArgsValidationError } from "./error-e_--t4mB.js";
+import { a as CommandResolutionError, c as CommandResolutionErrorOptions, d as isCommandNotFoundError, f as isCommandResolutionError, i as CommandNotFoundErrorOptions, l as hasPriorityValidationError, m as CLI_OPTIONS_DEFAULT, n as CommandNotFoundErrorCode, o as CommandResolutionErrorCode, p as ANONYMOUS_COMMAND_NAME, r as CommandNotFoundErrorKeys, s as CommandResolutionErrorKeys, t as CommandNotFoundError, u as isArgsValidationError } from "./error-DgUj3WPU.js";
 export { ANONYMOUS_COMMAND_NAME, type ArgSchema, type ArgToken, type ArgValues, type Args, ArgsValidationError, type ArgsValidationErrorCode, ArgsValidationErrorKeys, type Awaitable, CLI_OPTIONS_DEFAULT, type Command, type CommandContext, type CommandContextCore, type CommandContextExtension, type CommandContextParams, type CommandDecorator, type CommandExamplesFetcher, CommandNotFoundError, type CommandNotFoundErrorCode, CommandNotFoundErrorKeys, type CommandNotFoundErrorOptions, CommandResolutionError, type CommandResolutionErrorCode, CommandResolutionErrorKeys, type CommandResolutionErrorOptions, type CommandRunner, type DefaultGunshiParams, type ExtendContext, type ExtractArgs, type ExtractExtensions, type GunshiParams, type GunshiParamsConstraint, type LazyCommand, type MergeGunshiExtensions, type NormalizeToGunshiParams, type OnPluginExtension, type Plugin, type PluginContext, type PluginDependency, type PluginExtension, type PluginFunction, type PluginOptions, type PluginWithExtension, type PluginWithoutExtension, type Prettify, type RendererDecorator, type ValidationErrorsDecorator, createCommandContext, hasPriorityValidationError, isArgsValidationError, isCommandNotFoundError, isCommandResolutionError, plugin };

package/lib/plugin.js

@@ -1,5 +1,5 @@
 import { n as ANONYMOUS_COMMAND_NAME, r as CLI_OPTIONS_DEFAULT, t as createCommandContext } from "./context-CSecf6R5.js";
-import { n as ArgsValidationErrorKeys, t as ArgsValidationError } from "./resolver-CAlgxe_R-y4BytVTg.js";
-import { a as hasPriorityValidationError, c as isCommandResolutionError, i as CommandResolutionErrorKeys, n as CommandNotFoundErrorKeys, o as isArgsValidationError, r as CommandResolutionError, s as isCommandNotFoundError, t as CommandNotFoundError } from "./error-wB83kWiv.js";
-import { t as plugin } from "./plugin-CG94VzCl.js";
+import { n as ArgsValidationErrorKeys, t as ArgsValidationError } from "./resolver-CAlgxe_R-3pz9PVFu.js";
+import { a as hasPriorityValidationError, c as isCommandResolutionError, i as CommandResolutionErrorKeys, n as CommandNotFoundErrorKeys, o as isArgsValidationError, r as CommandResolutionError, s as isCommandNotFoundError, t as CommandNotFoundError } from "./error-pbHb3QAL.js";
+import { t as plugin } from "./plugin-Fea3gCnT.js";
 export { ANONYMOUS_COMMAND_NAME, ArgsValidationError, ArgsValidationErrorKeys, CLI_OPTIONS_DEFAULT, CommandNotFoundError, CommandNotFoundErrorKeys, CommandResolutionError, CommandResolutionErrorKeys, createCommandContext, hasPriorityValidationError, isArgsValidationError, isCommandNotFoundError, isCommandResolutionError, plugin };

package/lib/renderer.d.ts

@@ -1,4 +1,4 @@
-import { a as CommandContext, m as DefaultGunshiParams, y as GunshiParams } from "./types-lD5uzpd5.js";
+import { a as CommandContext, m as DefaultGunshiParams, y as GunshiParams } from "./types-jrddQ_Kw.js";
 //#region ../plugin-renderer/src/header.d.ts
 /**
  * Render the header.

package/lib/renderer.js

@@ -1,4 +1,4 @@
-import { i as renderHeader, n as renderValidationErrors, r as renderUsage } from "./src-Dr9mmkFc.js";
+import { i as renderHeader, n as renderValidationErrors, r as renderUsage } from "./src-0zuC_LJU.js";
 //#region src/renderer.ts
 /**
 * @author kazuya kawaguchi (a.k.a. kazupon)

package/lib/{resolver-CAlgxe_R-y4BytVTg.js → resolver-CAlgxe_R-3pz9PVFu.js}

@@ -1,5 +1,5 @@
-import { n as kebabnize, t as formatChoices } from "./utils-CJLgPw25.js";
-//#region ../../node_modules/.pnpm/args-tokens@1.0.0-beta.1/node_modules/args-tokens/lib/parser.js
+import { n as kebabnize, t as formatChoices } from "./utils-D-MmF6sM.js";
+//#region ../../node_modules/.pnpm/args-tokens@1.0.0/node_modules/args-tokens/lib/parser.js
 /**
 * forked from `nodejs/node` (`pkgjs/parseargs`)
 * repository url: https://github.com/nodejs/node (https://github.com/pkgjs/parseargs)
@@ -202,7 +202,7 @@ function hasLongOptionPrefix(arg) {
 	return arg.startsWith(LONG_OPTION_PREFIX) && arg.length > 2;
 }
 //#endregion
-//#region ../../node_modules/.pnpm/args-tokens@1.0.0-beta.1/node_modules/args-tokens/lib/resolver-CAlgxe_R.js
+//#region ../../node_modules/.pnpm/args-tokens@1.0.0/node_modules/args-tokens/lib/resolver-CAlgxe_R.js
 /**
 * Internal definitions shared by the modules of `args-tokens`.
 *

package/lib/{resolver-BezrTUr7.d.ts → resolver-Cbtx2IyH.d.ts}

@@ -1,4 +1,4 @@
-//#region ../../node_modules/.pnpm/args-tokens@1.0.0-beta.1/node_modules/args-tokens/lib/parser-DhESN1gR.d.ts
+//#region ../../node_modules/.pnpm/args-tokens@1.0.0/node_modules/args-tokens/lib/parser-DhESN1gR.d.ts
 //#region src/parser.d.ts
 /**
  * Entry point of argument parser.
@@ -86,7 +86,7 @@ interface ParserOptions {
  */
 declare function parseArgs(args: string[], options?: ParserOptions): ArgToken[];
 //#endregion
-//#region ../../node_modules/.pnpm/args-tokens@1.0.0-beta.1/node_modules/args-tokens/lib/resolver.d.ts
+//#region ../../node_modules/.pnpm/args-tokens@1.0.0/node_modules/args-tokens/lib/resolver.d.ts
 //#region src/resolver.d.ts
 /**
  * An argument schema definition for command-line argument parsing.

package/lib/{src-Dr9mmkFc.js → src-0zuC_LJU.js}

@@ -1,9 +1,9 @@
 import { n as ANONYMOUS_COMMAND_NAME, t as createCommandContext } from "./context-CSecf6R5.js";
-import { n as kebabnize } from "./utils-CJLgPw25.js";
+import { n as kebabnize } from "./utils-D-MmF6sM.js";
 import { resolveLazyCommand } from "./utils.js";
-import { n as ArgsValidationErrorKeys } from "./resolver-CAlgxe_R-y4BytVTg.js";
-import { c as isCommandResolutionError, o as isArgsValidationError, s as isCommandNotFoundError } from "./error-wB83kWiv.js";
-import { t as plugin } from "./plugin-CG94VzCl.js";
+import { n as ArgsValidationErrorKeys } from "./resolver-CAlgxe_R-3pz9PVFu.js";
+import { c as isCommandResolutionError, o as isArgsValidationError, s as isCommandNotFoundError } from "./error-pbHb3QAL.js";
+import { t as plugin } from "./plugin-Fea3gCnT.js";
 /**
 * @author kazuya kawaguchi (a.k.a. kazupon)
 * @license MIT

package/lib/{types-lD5uzpd5.d.ts → types-jrddQ_Kw.d.ts}

@@ -1,4 +1,4 @@
-import { i as Args, l as ArgToken, n as ArgSchema, r as ArgValues, t as ArgExplicitlyProvided } from "./resolver-BezrTUr7.js";
+import { i as Args, l as ArgToken, n as ArgSchema, r as ArgValues, t as ArgExplicitlyProvided } from "./resolver-Cbtx2IyH.js";
 //#region src/plugin/context.d.ts
 /**
  * Gunshi plugin context interface.
@@ -634,6 +634,9 @@ interface CliOptions<G extends GunshiParamsConstraint = DefaultGunshiParams> {
    * Output that must still appear — machine-readable results for an agent, warnings for the
    * CLI author — should use `console.log` / `console.warn`, not `ctx.log`.
    *
+   * The validation errors are not printed either, so `cli()` rejects with them, for the caller to
+   * report them (see {@linkcode CliOptions.renderValidationErrors}).
+   *
    * @default false
    */
   usageSilent?: boolean;
@@ -657,6 +660,12 @@ interface CliOptions<G extends GunshiParamsConstraint = DefaultGunshiParams> {
   renderHeader?: ((ctx: Readonly<CommandContext<G>>) => Promise<string>) | null;
   /**
    * Render function the validation errors.
+   *
+   * With the global options plugin, the rendered message is printed to stderr, the exit code is set
+   * to `1`, {@linkcode CliOptions.onErrorCommand} is called, and `cli()` resolves with `undefined`.
+   * Set it to `null` to report the validation errors yourself: nothing is printed, and `cli()` rejects
+   * with the `AggregateError`. A renderer that returns an empty message, and
+   * {@linkcode CliOptions.usageSilent}, also leave them to the caller.
    */
   renderValidationErrors?: ((ctx: Readonly<CommandContext<G>>, error: AggregateError) => Promise<string>) | null;
   /**
@@ -688,10 +697,14 @@ interface CliOptions<G extends GunshiParamsConstraint = DefaultGunshiParams> {
    */
   onAfterCommand?: (ctx: Readonly<CommandContext<G>>, result: string | undefined) => Awaitable<void>;
   /**
-   * Hook that runs when a command throws an error
+   * Hook that runs when a command throws an error, or when the arguments fail validation
+   *
+   * For the validation errors that the global options plugin has printed, the exit code is already `1`
+   * when the hook runs, so the hook can set another one, and `cli()` resolves after it. Any other
+   * error rejects `cli()` after the hook.
    *
    * @param ctx - The command context
-   * @param error - The error thrown during execution
+   * @param error - The error thrown during execution, or the `AggregateError` of the validation errors
    * @since v0.27.0
    */
   onErrorCommand?: (ctx: Readonly<CommandContext<G>>, error: Error) => Awaitable<void>;
@@ -860,9 +873,11 @@ interface RenderingOptions<G extends GunshiParamsConstraint = DefaultGunshiParam
   usage?: ((ctx: Readonly<CommandContext<G>>) => Promise<string>) | null;
   /**
    * Validation errors rendering configuration
-   * - `null`: Disable rendering
+   * - `null`: Disable rendering. `cli()` rejects with the validation errors, for the caller to report them
    * - `function`: Use custom renderer
    * - `undefined` (when omitted): Use default renderer
+   *
+   * See {@linkcode CliOptions.renderValidationErrors} for where the rendered message goes.
    */
   validationErrors?: ((ctx: Readonly<CommandContext<G>>, error: AggregateError) => Promise<string>) | null;
 }

package/lib/{utils-CJLgPw25.js → utils-D-MmF6sM.js}

@@ -1,4 +1,4 @@
-//#region ../../node_modules/.pnpm/args-tokens@1.0.0-beta.1/node_modules/args-tokens/lib/utils.js
+//#region ../../node_modules/.pnpm/args-tokens@1.0.0/node_modules/args-tokens/lib/utils.js
 /**
 * Entry point of utils.
 *

package/lib/utils.d.ts

@@ -1,5 +1,5 @@
-import { b as GunshiParamsConstraint, m as DefaultGunshiParams, p as Commandable, r as Command, x as LazyCommand } from "./types-lD5uzpd5.js";
-//#region ../../node_modules/.pnpm/args-tokens@1.0.0-beta.1/node_modules/args-tokens/lib/utils.d.ts
+import { b as GunshiParamsConstraint, m as DefaultGunshiParams, p as Commandable, r as Command, x as LazyCommand } from "./types-jrddQ_Kw.js";
+//#region ../../node_modules/.pnpm/args-tokens@1.0.0/node_modules/args-tokens/lib/utils.d.ts
 //#region src/utils.d.ts
 /**
  * Entry point of utils.

package/lib/utils.js

@@ -1,4 +1,4 @@
-import { n as kebabnize } from "./utils-CJLgPw25.js";
+import { n as kebabnize } from "./utils-D-MmF6sM.js";
 //#region src/utils.ts
 /**
 * @author kazuya kawaguchi (a.k.a. kazupon)

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "gunshi",
   "description": "Modern javascript command-line library",
-  "version": "1.0.0-beta.2",
+  "version": "1.0.0-rc.2",
   "author": {
     "name": "kazuya kawaguchi",
     "email": "kawakazu80@gmail.com"
@@ -32,7 +32,8 @@
   },
   "type": "module",
   "files": [
-    "lib"
+    "lib",
+    "skills"
   ],
   "module": "lib/index.js",
   "exports": {
@@ -108,13 +109,13 @@
     }
   },
   "devDependencies": {
-    "@gunshi/plugin-global": "1.0.0-beta.2",
-    "@gunshi/plugin-i18n": "1.0.0-beta.2",
-    "@gunshi/plugin-renderer": "1.0.0-beta.2",
-    "@gunshi/resources": "1.0.0-beta.2",
-    "@gunshi/shared": "1.0.0-beta.2",
-    "@types/node": "^25.6.2",
-    "args-tokens": "1.0.0-beta.1",
+    "@gunshi/plugin-global": "1.0.0-rc.2",
+    "@gunshi/plugin-i18n": "1.0.0-rc.2",
+    "@gunshi/plugin-renderer": "1.0.0-rc.2",
+    "@gunshi/resources": "1.0.0-rc.2",
+    "@gunshi/shared": "1.0.0-rc.2",
+    "@types/node": "^26.0.0",
+    "args-tokens": "1.0.0",
     "deno": "^2.7.14",
     "jsr": "^0.14.3",
     "jsr-exports-lint": "^0.4.2",

package/skills/gunshi/SKILL.md

@@ -0,0 +1,35 @@
+---
+name: gunshi
+description: Use this skill when building a command-line interface with the Gunshi library, or setting up a repository that uses it.
+---
+
+## Step 1: Install @gunshi/docs
+
+The docs must match the installed Gunshi version. Read `version` from
+`node_modules/gunshi/package.json`, then install the docs at exactly that version
+as a dev dependency with the user's preferred package manager:
+
+```sh
+pnpm add -D @gunshi/docs@<gunshi version>
+```
+
+Alternatively, ask the user whether to set up Gunshi with its setup command.
+If they agree, run it with `--yes` to skip its interactive prompt. It installs
+`gunshi` and `@gunshi/docs` at the version given here:
+
+```sh
+npx @gunshi/docs@<gunshi version> --yes
+```
+
+## Step 2: Update AGENTS.md / CLAUDE.md
+
+Ensure that the agent instructions contain the following:
+
+```md
+# Learning more about Gunshi
+
+This repository uses the Gunshi library for its command-line interface.
+
+Before writing any Gunshi code, first read `node_modules/@gunshi/docs/README.md`
+**completely**, and follow the links in the file when required.
+```