@gunshi/plugin-global 0.37.3 → 1.0.0-beta.1

package/README.md

@@ -78,6 +78,31 @@ 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
 
+### Commands That Take the Name
+
+`help` and `version` are not reserved. A command may declare an argument of its own under either name, and gunshi merges the arguments of a command over the global options, so the command's argument wins:
+
+```js
+import { define } from 'gunshi'
+
+const release = define({
+  name: 'release',
+  args: {
+    version: { type: 'string', description: 'Version to release' }
+  },
+  run: ctx => console.log(`releasing ${ctx.values.version}`)
+})
+```
+
+`my-cli release --version 1.2.3` runs the command with `1.2.3`, rather than printing the version of the CLI. Two things follow from the command owning the name:
+
+- The option no longer does what this plugin does automatically. `my-cli release --version` does not print the version of the CLI, and `--help` on a command that takes the name no longer shows its usage by itself — the command receives the value and decides, and it can still call `showUsage()` or `showVersion()` from `ctx.extensions['g:global']`
+- The short name goes with it. The global schema is replaced whole, so `-v` (or `-h`) is no longer defined unless the command declares a `short` of its own
+
+Other commands of the same CLI are unaffected, and so is the entry command unless it declares the name itself.
+
+One case is left to this plugin on purpose: a schema that is identical to the one this plugin registers, field for field, cannot be told apart from it, so `version: { type: 'boolean', short: 'v', description: 'Display this version' }` still prints the version of the CLI. Any difference at all — a description of your own, an extra property, another type — makes the argument the command's.
+
 ## 🧩 Context Extensions
 
 When using the global options plugin, your command context is extended via `ctx.extensions['g:global']`.

package/lib/index.d.ts

@@ -1,11 +1,5 @@
 import { Awaitable, PluginWithExtension } from "@gunshi/plugin";
-
 //#region src/extension.d.ts
-/**
-* @author kazuya kawaguchi (a.k.a. kazupon)
-* @license MIT
-*/
-
 /**
  * Extended command context which provides utilities via global options plugin.
  * These utilities are available via `CommandContext.extensions['g:global']`.
@@ -46,33 +40,12 @@ interface GlobalExtension {
 declare const BUILT_IN_PREFIX = "_";
 declare const PLUGIN_PREFIX = "g";
 declare const BUILT_IN_KEY_SEPARATOR = ":";
-//#endregion
-//#region ../plugin-i18n/src/types.d.ts
-
-//#endregion
-//#region ../plugin-i18n/src/helpers.d.ts
-
-//#endregion
-//#region ../plugin-i18n/src/translation.d.ts
-
-//#endregion
-//#region ../gunshi/src/index.d.ts
-
 //#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 ../shared/src/localization.d.ts
-
-//#endregion
-//#region ../shared/src/utils.d.ts
-
-//#endregion
-//#region ../shared/src/index.d.ts
-
 //#endregion
 //#region src/types.d.ts
 /**

package/lib/index.js

@@ -67,16 +67,21 @@ const pluginId = namespacedId("global");
 * @returns A command decorator that adds global options handling
 */
 const decorator = (baseRunner) => async (ctx) => {
-	const { values, validationError, extensions: { [pluginId]: { showVersion, showHeader, showUsage, showValidationErrors } } } = ctx;
+	/**
+	* NOTE(kazupon): the core puts the globals still in effect on `env.globalOptions`. A command that
+	* 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;
 	}
-	if (values.version) return showVersion();
+	if (values.version && globalOptions?.has("version")) return showVersion();
 	const buf = [];
 	const header = await showHeader();
 	if (header) buf.push(header);
-	if (values.help) {
+	if (values.help && globalOptions?.has("help")) {
 		const usage = await showUsage();
 		if (usage) {
 			buf.push(usage);

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@gunshi/plugin-global",
   "description": "global options plugin for gunshi",
-  "version": "0.37.3",
+  "version": "1.0.0-beta.1",
   "author": {
     "name": "kazuya kawaguchi",
     "email": "kawakazu80@gmail.com"
@@ -51,15 +51,15 @@
     }
   },
   "dependencies": {
-    "@gunshi/plugin": "0.37.3"
+    "@gunshi/plugin": "1.0.0-beta.1"
   },
   "devDependencies": {
+    "@gunshi/shared": "1.0.0-beta.1",
     "deno": "^2.7.14",
     "jsr": "^0.14.3",
     "jsr-exports-lint": "^0.4.2",
     "publint": "^0.3.20",
-    "tsdown": "0.21.0",
-    "@gunshi/shared": "0.37.3"
+    "tsdown": "0.22.14"
   },
   "scripts": {
     "build": "tsdown",