@gunshi/plugin-global 1.0.0-beta.2 → 1.0.0-rc.2

package/README.md

@@ -127,9 +127,9 @@ Available extensions:
 
 - **`showHeader(): Awaitable<string | undefined>`**: Display the application header. Returns `undefined` if no `renderHeader` function is provided in the CLI configuration.
 
-- **`showUsage(): Awaitable<string | undefined>`**: Display the command usage information. This is automatically called when `--help` is used. Returns `undefined` if no `renderUsage` function is provided.
+- **`showUsage(): Awaitable<string | undefined>`**: Display the command usage information, with the header as its title. This is automatically called when `--help` is used. Returns `undefined` if no `renderUsage` function is provided.
 
-- **`showValidationErrors(error: AggregateError): Awaitable<string | undefined>`**: Display validation errors when argument validation fails. Returns `undefined` if `renderValidationErrors` is null.
+- **`showValidationErrors(error: AggregateError): Awaitable<string | undefined>`**: Display validation errors when argument validation fails. The rendered message is printed to stderr, unless it is empty or `usageSilent` is set. Returns `undefined` if `renderValidationErrors` is null.
 
 ### Usage Example
 
@@ -143,15 +143,12 @@ const command = {
     // Access global extensions
     const { showVersion, showHeader } = ctx.extensions[globalId]
 
+    // Show the custom header before the output of the command (it prints the header itself)
+    await showHeader()
+
     // Manually show version if needed
     console.log(`Deploying with CLI version: ${showVersion()}`)
 
-    // Show custom header
-    const header = await showHeader()
-    if (header) {
-      console.log(header)
-    }
-
     // Your command logic here...
   }
 }

package/lib/index.d.ts

@@ -18,13 +18,13 @@ interface GlobalExtension {
    */
   showHeader: () => Awaitable<string | undefined>;
   /**
-   * Show the usage of the application. if `--help` option is specified, it will print the usage to the console.
+   * Show the usage of the application, with the header as its title. if `--help` option is specified, it will print the usage to the console.
    *
-   * @returns The usage of the application, or `undefined` if the `renderUsage` is not specified.
+   * @returns The header and the usage of the application, or `undefined` if the `renderUsage` is not specified.
    */
   showUsage: () => Awaitable<string | undefined>;
   /**
-   * Show validation errors. This is called when argument validation fails.
+   * Show validation errors. This is called when argument validation fails. The rendered message is printed to stderr, unless it is empty or `usageSilent` is set.
    *
    * @param error - The aggregate error containing validation failures
    * @returns The rendered error message, or `undefined` if `renderValidationErrors` is null

package/lib/index.js

@@ -61,6 +61,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
@@ -72,27 +102,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
@@ -126,19 +154,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;
 			}
 		}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@gunshi/plugin-global",
   "description": "global options plugin for gunshi",
-  "version": "1.0.0-beta.2",
+  "version": "1.0.0-rc.2",
   "author": {
     "name": "kazuya kawaguchi",
     "email": "kawakazu80@gmail.com"
@@ -51,10 +51,10 @@
     }
   },
   "dependencies": {
-    "@gunshi/plugin": "1.0.0-beta.2"
+    "@gunshi/plugin": "1.0.0-rc.2"
   },
   "devDependencies": {
-    "@gunshi/shared": "1.0.0-beta.2",
+    "@gunshi/shared": "1.0.0-rc.2",
     "deno": "^2.7.14",
     "jsr": "^0.14.3",
     "jsr-exports-lint": "^0.4.2",