@gunshi/plugin-global 0.26.3

package/LICENSE

@@ -0,0 +1,20 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 kazuya kawaguchi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+the Software, and to permit persons to whom the Software is furnished to do so,
+subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,145 @@
+# @gunshi/plugin-global
+
+> global options plugin for gunshi.
+
+This plugin provides standard global options (`--help` and `--version`) for all commands in your CLI application. It's installed by default in gunshi, ensuring consistent behavior across all CLI applications.
+
+## 💿 Installation
+
+```sh
+# npm
+npm install --save @gunshi/plugin-global
+
+# pnpm
+pnpm add @gunshi/plugin-global
+
+# yarn
+yarn add @gunshi/plugin-global
+
+# deno
+deno add jsr:@gunshi/plugin-global
+
+# bun
+bun add @gunshi/plugin-global
+```
+
+## 🚀 Usage
+
+```ts
+import global from '@gunshi/plugin-global'
+import { cli } from 'gunshi'
+
+const command = {
+  name: 'my-command',
+  args: {
+    target: {
+      type: 'string',
+      description: 'Target to process'
+    }
+  },
+  run: ctx => {
+    console.log(`Processing ${ctx.values.target}`)
+  }
+}
+
+await cli(process.argv.slice(2), command, {
+  name: 'my-cli',
+  version: '1.0.0',
+  plugins: [
+    global() // Adds --help and --version options
+  ]
+})
+```
+
+<!-- eslint-disable markdown/no-missing-label-refs -->
+
+> [!TIP]
+> This plugin is installed in gunshi **by default**. You don't need to explicitly add it unless you've disabled default plugins.
+
+<!-- eslint-enable markdown/no-missing-label-refs -->
+
+## ✨ Features
+
+### Global Options
+
+This plugin automatically adds the following options to all commands:
+
+- **`--help`, `-h`**: Display the command usage and available options
+- **`--version`, `-v`**: Display the application version
+
+### Automatic Behavior
+
+When these options are used:
+
+- **With `--help`**: The command execution is bypassed, and the usage information is displayed instead
+- **With `--version`**: The command execution is bypassed, and only the version number is printed
+
+## 🧩 Context Extensions
+
+When using the global options plugin, your command context is extended via `ctx.extensions['g:global']`.
+
+<!-- eslint-disable markdown/no-missing-label-refs -->
+
+> [!IMPORTANT]
+> This plugin extension is namespaced in `CommandContext.extensions` using this plugin ID `g:global` by the gunshi plugin system.
+
+<!-- eslint-enable markdown/no-missing-label-refs -->
+
+Available extensions:
+
+- **`showVersion(): string`**: Display the application version. Returns `'unknown'` if no version is specified in the CLI configuration.
+
+- **`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.
+
+- **`showValidationErrors(error: AggregateError): Awaitable<string | undefined>`**: Display validation errors when argument validation fails. Returns `undefined` if `renderValidationErrors` is null.
+
+### Usage Example
+
+```ts
+import global, { pluginId } from '@gunshi/plugin-global'
+import { cli } from 'gunshi'
+
+const command = {
+  name: 'deploy',
+  run: async ctx => {
+    // Access globals extensions
+    const { showVersion, showHeader } = ctx.extensions[pluginId]
+
+    // 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...
+  }
+}
+
+await cli(process.argv.slice(2), command, {
+  name: 'deploy-cli',
+  version: '2.1.0',
+  plugins: [global()],
+
+  // Optional: Custom header renderer
+  renderHeader: async () => {
+    return `
+╔══════════════════════╗
+║   Deploy CLI v2.1.0  ║
+╚══════════════════════╝
+`
+  }
+})
+```
+
+## 📚 API References
+
+See the [API References](./docs/index.md)
+
+## ©️ License
+
+[MIT](http://opensource.org/licenses/MIT)

package/lib/index.d.ts

@@ -0,0 +1,74 @@
+import { Awaitable, PluginWithExtension } from "@gunshi/plugin";
+
+//#region src/extension.d.ts
+/**
+* Extended command context which provides utilities via global options plugin.
+* These utilities are available via `CommandContext.extensions['g:global']`.
+*/
+
+/**
+ * Extended command context which provides utilities via global options plugin.
+ * These utilities are available via `CommandContext.extensions['g:global']`.
+ */
+interface GlobalCommandContext {
+  /**
+   * Show the version of the application. if `--version` option is specified, it will print the version to the console.
+   * @returns The version of the application, or `unknown` if the version is not specified.
+   */
+  showVersion: () => string;
+  /**
+   * Show the header of the application.
+   * @returns The header of the application, or `undefined` if the `renderHeader` is not specified.
+   */
+  showHeader: () => Awaitable<string | undefined>;
+  /**
+   * Show the usage of the application. 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.
+   */
+  showUsage: () => Awaitable<string | undefined>;
+  /**
+   * Show validation errors. This is called when argument validation fails.
+   * @param error The aggregate error containing validation failures
+   * @returns The rendered error message, or `undefined` if `renderValidationErrors` is null
+   */
+  showValidationErrors: (error: AggregateError) => Awaitable<string | undefined>;
+} //#endregion
+//#region ../shared/src/constants.d.ts
+/**
+ * @author kazuya kawaguchi (a.k.a. kazupon)
+ * @license MIT
+ */
+declare const BUILT_IN_PREFIX = "_";
+declare const PLUGIN_PREFIX = "g";
+declare const BUILT_IN_KEY_SEPARATOR = ":";
+
+//#endregion
+//#region ../shared/src/types.d.ts
+/**
+ * Generate a namespaced key.
+ */
+type GenerateNamespacedKey<Key extends string, Prefixed extends string = typeof BUILT_IN_PREFIX> = `${Prefixed}${typeof BUILT_IN_KEY_SEPARATOR}${Key}`;
+
+//#endregion
+//#region src/types.d.ts
+/**
+ * Command i18n built-in arguments keys.
+ */
+/**
+ * The unique identifier for the global options plugin.
+ */
+declare const pluginId: GenerateNamespacedKey<'global', typeof PLUGIN_PREFIX>;
+/**
+ * Type representing the unique identifier for the global options plugin.
+ */
+type PluginId = typeof pluginId;
+
+//#endregion
+//#region src/index.d.ts
+/**
+ * global options plugin
+ */
+declare function global(): PluginWithExtension<GlobalCommandContext>;
+
+//#endregion
+export { GlobalCommandContext, PluginId, global as default, pluginId };

package/lib/index.js

@@ -0,0 +1,122 @@
+import { plugin } from "@gunshi/plugin";
+
+//#region ../shared/src/constants.ts
+/**
+* @author kazuya kawaguchi (a.k.a. kazupon)
+* @license MIT
+*/
+const BUILT_IN_PREFIX = "_";
+const PLUGIN_PREFIX = "g";
+const ARG_PREFIX = "arg";
+const BUILT_IN_KEY_SEPARATOR = ":";
+const BUILD_IN_PREFIX_AND_KEY_SEPARATOR = `${BUILT_IN_PREFIX}${BUILT_IN_KEY_SEPARATOR}`;
+const ARG_PREFIX_AND_KEY_SEPARATOR = `${ARG_PREFIX}${BUILT_IN_KEY_SEPARATOR}`;
+const COMMON_ARGS = {
+	help: {
+		type: "boolean",
+		short: "h",
+		description: "Display this help message"
+	},
+	version: {
+		type: "boolean",
+		short: "v",
+		description: "Display this version"
+	}
+};
+
+//#endregion
+//#region ../shared/src/utils.ts
+function namespacedId(id) {
+	return `${PLUGIN_PREFIX}${BUILT_IN_KEY_SEPARATOR}${id}`;
+}
+
+//#endregion
+//#region src/types.ts
+/**
+* The unique identifier for the global options plugin.
+*/
+const pluginId = namespacedId("global");
+
+//#endregion
+//#region src/decorator.ts
+/**
+* Decorator function to extend the command with global options.
+*/
+const decorator = (baseRunner) => async (ctx) => {
+	const { values, validationError, extensions: { [pluginId]: { showVersion, showHeader, showUsage, showValidationErrors } } } = ctx;
+	if (values.version) return showVersion();
+	const buf = [];
+	const header = await showHeader();
+	if (header) buf.push(header);
+	if (values.help) {
+		const usage = await showUsage();
+		if (usage) {
+			buf.push(usage);
+			return buf.join("\n");
+		}
+		return;
+	}
+	if (validationError) return await showValidationErrors(validationError);
+	return baseRunner(ctx);
+};
+var decorator_default = decorator;
+
+//#endregion
+//#region src/extension.ts
+function extension(ctx) {
+	return {
+		showVersion: () => {
+			const version = ctx.env.version || "unknown";
+			if (!ctx.env.usageSilent) ctx.log(version);
+			return version;
+		},
+		showHeader: async () => {
+			let header;
+			if (ctx.env.renderHeader != null) {
+				header = await ctx.env.renderHeader(ctx);
+				if (header) {
+					ctx.log(header);
+					ctx.log();
+				}
+			}
+			return header;
+		},
+		showUsage: async () => {
+			if (ctx.env.renderUsage != null) {
+				const usage = await ctx.env.renderUsage(ctx);
+				if (usage) {
+					ctx.log(usage);
+					return 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);
+				return message;
+			}
+		}
+	};
+}
+
+//#endregion
+//#region src/index.ts
+/**
+* global options plugin
+*/
+function global() {
+	return plugin({
+		id: pluginId,
+		name: "global options",
+		extension,
+		setup(ctx) {
+			for (const [name, schema] of Object.entries(COMMON_ARGS)) ctx.addGlobalOption(name, schema);
+			ctx.decorateCommand(decorator_default);
+		}
+	});
+}
+
+//#endregion
+export { global as default, pluginId };

package/package.json

@@ -0,0 +1,72 @@
+{
+  "name": "@gunshi/plugin-global",
+  "description": "global options plugin for gunshi",
+  "version": "0.26.3",
+  "author": {
+    "name": "kazuya kawaguchi",
+    "email": "kawakazu80@gmail.com"
+  },
+  "license": "MIT",
+  "funding": "https://github.com/sponsors/kazupon",
+  "bugs": {
+    "url": "https://github.com/kazupon/gunshi/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kazupon/gunshi.git",
+    "directory": "packages/plugin-global"
+  },
+  "keywords": [
+    "gunshi",
+    "plugin",
+    "cli"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">= 20"
+  },
+  "type": "module",
+  "files": [
+    "lib"
+  ],
+  "module": "lib/index.js",
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "import": "./lib/index.js",
+      "require": "./lib/index.js",
+      "default": "./lib/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "types": "lib/index.d.ts",
+  "typesVersions": {
+    "*": {
+      "*": [
+        "./lib/*",
+        "./*"
+      ]
+    }
+  },
+  "dependencies": {
+    "@gunshi/plugin": "0.26.3"
+  },
+  "devDependencies": {
+    "deno": "^2.3.3",
+    "jsr": "^0.13.4",
+    "jsr-exports-lint": "^0.4.1",
+    "publint": "^0.3.12",
+    "tsdown": "^0.12.3",
+    "typedoc": "^0.28.4",
+    "typedoc-plugin-markdown": "^4.6.3",
+    "@gunshi/shared": "0.26.3"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "build:docs": "typedoc --excludeInternal",
+    "lint:jsr": "jsr publish --dry-run --allow-dirty",
+    "typecheck:deno": "deno check ./src"
+  }
+}