Add functions to better support commands provided by global commands.

Author: iclanton

common/changes/@microsoft/rush/rush-published-versions-plugin_2026-03-15-04-22.json

@@ -0,0 +1,10 @@
+{
+  "changes": [
+    {
+      "packageName": "@microsoft/rush",
+      "comment": "Add `customParametersByLongName` and `setHandled()` to `IGlobalCommand`, enabling Rush plugins to implement native global commands. Plugins can now define global commands with an empty `shellCommand`, handle execution via the `runGlobalCustomCommand` hook, and access parsed command-line parameters.",
+      "type": "none"
+    }
+  ],
+  "packageName": "@microsoft/rush"
+}

common/reviews/api/rush-lib.api.md

@@ -512,6 +512,8 @@ export interface IGetChangedProjectsOptions {
 
 // @beta
 export interface IGlobalCommand extends IRushCommand {
+    getCustomParametersByLongName<TParameter extends CommandLineParameter>(longName: string): TParameter;
+    setHandled(): void;
 }
 
 // @public
@@ -1500,7 +1502,7 @@ export class RushLifecycleHooks {
     variant: string | undefined
     ]>;
     readonly beforeInstall: AsyncSeriesHook<[
-    command: IGlobalCommand,
+    command: IRushCommand,
     subspace: Subspace,
     variant: string | undefined
     ]>;

libraries/rush-lib/src/cli/scriptActions/GlobalScriptAction.ts

@@ -5,6 +5,7 @@ import * as path from 'node:path';
 
 import type { AsyncSeriesHook } from 'tapable';
 
+import type { CommandLineParameter } from '@rushstack/ts-command-line';
 import {
   FileSystem,
   type IPackageJson,
@@ -45,6 +46,9 @@ export class GlobalScriptAction extends BaseScriptAction<IGlobalCommandConfig> {
   private readonly _autoinstallerName: string;
   private readonly _autoinstallerFullPath: string;
 
+  private _customParametersByLongName: ReadonlyMap<string, CommandLineParameter> | undefined;
+  private _isHandled: boolean = false;
+
   public constructor(options: IGlobalScriptActionOptions) {
     super(options);
     this._shellCommand = options.shellCommand;
@@ -93,6 +97,37 @@ export class GlobalScriptAction extends BaseScriptAction<IGlobalCommandConfig> {
     this.defineScriptParameters();
   }
 
+  /**
+   * {@inheritDoc IGlobalCommand.setHandled}
+   */
+  public setHandled(): void {
+    this._isHandled = true;
+  }
+
+  /**
+   * {@inheritDoc IGlobalCommand.getCustomParametersByLongName}
+   */
+  public getCustomParametersByLongName<TParameter extends CommandLineParameter>(
+    longName: string
+  ): TParameter {
+    if (!this._customParametersByLongName) {
+      const map: Map<string, CommandLineParameter> = new Map();
+      for (const [parameterJson, parameter] of this.customParameters) {
+        map.set(parameterJson.longName, parameter);
+      }
+      this._customParametersByLongName = map;
+    }
+
+    const parameter: CommandLineParameter | undefined = this._customParametersByLongName.get(longName);
+    if (!parameter) {
+      throw new Error(
+        `The command "${this.actionName}" does not have a custom parameter with long name "${longName}".`
+      );
+    }
+
+    return parameter as TParameter;
+  }
+
   private async _prepareAutoinstallerNameAsync(): Promise<void> {
     const autoInstaller: Autoinstaller = new Autoinstaller({
       autoinstallerName: this._autoinstallerName,
@@ -117,6 +152,20 @@ export class GlobalScriptAction extends BaseScriptAction<IGlobalCommandConfig> {
       await hookForAction.promise(this);
     }
 
+    // If a plugin hook called setHandled(), the command has been fully handled.
+    // Skip the default shell command execution.
+    if (this._isHandled) {
+      return;
+    }
+
+    if (this._shellCommand === '') {
+      throw new Error(
+        `The custom command "${this.actionName}" has an empty "shellCommand" value, but no plugin ` +
+          'called setHandled() for this command. An empty "shellCommand" is intended for global ' +
+          'commands whose implementation is provided entirely by a Rush plugin.'
+      );
+    }
+
     const additionalPathFolders: string[] =
       this.commandLineConfiguration?.additionalPathFolders.slice() || [];
 

libraries/rush-lib/src/pluginFramework/RushLifeCycle.ts

@@ -3,6 +3,8 @@
 
 import { AsyncParallelHook, AsyncSeriesHook, HookMap } from 'tapable';
 
+import type { CommandLineParameter } from '@rushstack/ts-command-line';
+
 import type { ITelemetryData } from '../logic/Telemetry';
 import type { PhasedCommandHooks } from './PhasedCommandHooks';
 import type { Subspace } from '../api/Subspace';
@@ -23,7 +25,17 @@ export interface IRushCommand {
  * @beta
  */
 export interface IGlobalCommand extends IRushCommand {
-  // Nothing added.
+  /**
+   * Get a parameter by its long name (e.g. "--output-path") that was defined in command-line.json for this command.
+   * If the parameter was not defined or not provided on the command line, this will throw.
+   */
+  getCustomParametersByLongName<TParameter extends CommandLineParameter>(longName: string): TParameter;
+
+  /**
+   * Call this from a plugin hook to indicate that the command has been fully handled
+   * by the plugin. When set, the default shell command execution will be skipped.
+   */
+  setHandled(): void;
 }
 
 /**
@@ -94,7 +106,7 @@ export class RushLifecycleHooks {
    * The hook to run between preparing the common/temp folder and invoking the package manager during "rush install" or "rush update".
    */
   public readonly beforeInstall: AsyncSeriesHook<
-    [command: IGlobalCommand, subspace: Subspace, variant: string | undefined]
+    [command: IRushCommand, subspace: Subspace, variant: string | undefined]
   > = new AsyncSeriesHook(['command', 'subspace', 'variant'], 'beforeInstall');
 
   /**