[rush] (BREAKING CHANGE) Overhaul watch-mode to facilitate orchestration (#5378)

## Summary

Completely retools the watch engine in Rush to facilitate better interaction with plugins that wish to orchestrate the build process. Makes the Rush execution engine stateful across an entire Rush watch session.

### BREAKING CHANGES

- `PhasedCommandHooks` now has only two hooks: `createOperationsAsync` and `onGraphCreatedAsync`. All other hooks have been moved to `OperationGraphHooks`, accessible via `operationGraph.hooks` inside the `onGraphCreatedAsync` callback.
- `createOperations` is now `createOperationsAsync`, and the properties on the `ICreateOperationsContext` parameter have changed: `isInitial`, `projectsInUnknownState`, `phaseOriginal`, and `invalidateOperation` have been removed; `generateFullGraph` and `includePhaseDeps` have been added.
- All manipulation of the runtime graph and taps into the build process are now in the `OperationGraphHooks` class. Tap `operationGraph.hooks` for:
  - `configureIteration` — synchronous hook to select which operations run in the next iteration
  - `beforeExecuteIterationAsync` — replaces `beforeExecuteOperationsAsync`
  - `afterExecuteIterationAsync` — replaces `afterExecuteOperationsAsync`
  - `beforeExecuteOperationAsync` — moved from `PhasedCommandHooks`
  - `afterExecuteOperationAsync` — moved from `PhasedCommandHooks`
  - `createEnvironmentForOperation` — moved from `PhasedCommandHooks`
  - `beforeLog` — moved from `PhasedCommandHooks`; now invoked by the graph before writing telemetry
  - `onIdle` — replaces `waitingForChanges` (moved from `PhasedCommandHooks`)
  - `onExecutionStatesUpdated`, `onEnableStatesChanged`, `onIterationScheduled`, `onGraphStateChanged`, `onInvalidateOperations` — new hooks
- `IOperationRunnerContext` now includes `getInvalidateCallback()`, which returns a lightweight `(reason: string) => void` callback that marks the current operation for re-execution. This replaces the previous `invalidateOperation` on `ICreateOperationsContext` and removes the need for runners to capture an `IOperationGraph` reference.
- `IOperationRunner.executeAsync` now takes an optional second parameter `lastState?: IOperationLastState`, providing the previous execution result to inform incremental behavior (e.g. choosing an initial vs. incremental command).
- `IBaseOperationExecutionResult.getStateHashComponents()` now returns a structured `IOperationStateHashComponents` interface (`{ dependencies, local, config }`) instead of a flat `ReadonlyArray<string>`.
- `IBaseOperationExecutionResult.metadataFolderPath` is now `string` (was `string | undefined`).

## Details

The new lifecycle of a Rush phased command is that the command first invokes `createOperationsAsync` to create the session-long operation graph. This set of operations is then passed into `onGraphCreatedAsync`, which constructs an `IOperationGraph` that owns the lifecycle of the execution session.

There is a new watch option `includeAllProjectsInWatchGraph` (in `command-line.json`) that, if set to true, will cause Rush to build the graph with all projects in `rush.json`, regardless of CLI selection parameters. Selected projects will only affect which projects are enabled for execution during the initial run. This also allows for a bare command, e.g. `rush start`, to select no projects. This feature is intended for use with plugins that offer the ability to alter the enabled/disabled states of operations in the graph while the session is ongoing. For an example, see `@rushstack/rush-serve-plugin`, which facilitates altering these states via Web Socket messages.

### Runner self-invalidation

Long-lived runners (e.g. IPC processes, file watchers) can now request re-execution directly via `context.getInvalidateCallback()`. This returns a minimal closure that delegates to `IOperationGraph.invalidateOperations()`, without the runner needing access to the graph or `Operation` object. The `IPCOperationRunner` uses this internally to handle `requestRun` IPC messages from child processes.

### Error handling

Operation runner errors are now uniformly caught and wrapped in `OperationError` by `OperationExecutionRecord.executeAsync`, rather than requiring each runner implementation to handle its own error wrapping.

All in-repo plugins that interact with the Rush execution graph have also been updated.

## How it was tested

Added unit tests for all functionality of the new `IOperationGraph` API contract (633 tests passing).
Manual validation via the rushstack repo's `rush start` command for the CLI interaction (enable/disable debug or verbose, alter parallelism, pause/resume, kick a single build, invalidate, close runners).

## Impacted documentation

All watch-mode documentation. Plugin documentation for phased commands.

New docs added in this PR:
- `docs/rush/phased-commands.md` — architecture reference for the phased command execution model, `OperationGraphHooks`, `IOperationGraph` API, and `IOperationRunner` contract
- `docs/rush/plugin-migration-guide.md` — hook-by-hook migration guide for plugin authors upgrading from the previous API

Author: dmichon-msft

apps/rush/package.json

@@ -48,6 +48,7 @@
     "@rushstack/rush-amazon-s3-build-cache-plugin": "workspace:*",
     "@rushstack/rush-azure-storage-build-cache-plugin": "workspace:*",
     "@rushstack/rush-http-build-cache-plugin": "workspace:*",
+    "@rushstack/rush-serve-plugin": "workspace:*",
     "@types/semver": "7.7.1"
   },
   "exports": {

apps/rush/src/start-dev.ts

@@ -29,6 +29,7 @@ function includePlugin(pluginName: string, pluginPackageName?: string): void {
 includePlugin('rush-amazon-s3-build-cache-plugin');
 includePlugin('rush-azure-storage-build-cache-plugin');
 includePlugin('rush-http-build-cache-plugin');
+includePlugin('rush-serve-plugin');
 // Including this here so that developers can reuse it without installing the plugin a second time
 includePlugin('rush-azure-interactive-auth-plugin', '@rushstack/rush-azure-storage-build-cache-plugin');
 

common/changes/@microsoft/rush/watch-rework_2025-09-26-23-50.json

@@ -0,0 +1,10 @@
+{
+  "changes": [
+    {
+      "packageName": "@microsoft/rush",
+      "comment": "(PLUGIN BREAKING CHANGE) Overhaul watch-mode commands such that the graph is only created once at the start of command invocation, along with a stateful manager object. Plugins may now access the manager object and use it to orchestrate and tap into the build process.",
+      "type": "none"
+    }
+  ],
+  "packageName": "@microsoft/rush"
+}

common/config/rush-plugins/rush-serve-plugin.json

@@ -0,0 +1,7 @@
+{
+  "$schema": "https://developer.microsoft.com/json-schemas/rush/v5/rush-serve-plugin-options.schema.json",
+  "phasedCommands": ["start"],
+  "portParameterLongName": "--port",
+  "buildStatusWebSocketPath": "/ws",
+  "logServePath": "/logs"
+}

common/config/rush/command-line.json

@@ -245,24 +245,25 @@
       // Used for very simple builds that don't support CLI arguments like `--production` or `--fix`
       "name": "_phase:lite-build",
       "dependencies": {
-        "upstream": ["_phase:lite-build", "_phase:build"]
+        "upstream": ["_phase:build"]
       },
       "missingScriptBehavior": "silent",
       "allowWarningsOnSuccess": false
     },
     {
       "name": "_phase:build",
       "dependencies": {
-        "self": ["_phase:lite-build"],
-        "upstream": ["_phase:build"]
+        // Don't need to declare the dependency on _phase:build because it is transitive via _phase:lite-build
+        "self": ["_phase:lite-build"]
       },
       "missingScriptBehavior": "log",
       "allowWarningsOnSuccess": false
     },
     {
       "name": "_phase:test",
       "dependencies": {
-        "self": ["_phase:lite-build", "_phase:build"]
+        // Dependency on _phase:lite-build is transitive via _phase:build
+        "self": ["_phase:build"]
       },
       "missingScriptBehavior": "silent",
       "allowWarningsOnSuccess": false
@@ -494,6 +495,14 @@
       "associatedPhases": ["_phase:build", "_phase:test"],
       "associatedCommands": ["build", "rebuild", "test", "retest"]
     },
+    {
+      "longName": "--port",
+      "parameterKind": "integer",
+      "argumentName": "PORT",
+      "description": "The port to use for the server",
+      "associatedPhases": [],
+      "associatedCommands": ["start"]
+    },
     {
       "longName": "--update-snapshots",
       "parameterKind": "flag",

common/config/rush/experiments.json

@@ -88,7 +88,7 @@
    * of `_phase:<name>` if they exist. The created child process will be provided with an IPC channel and expected to persist
    * across invocations.
    */
-  // "useIPCScriptsInWatchMode": true,
+  "useIPCScriptsInWatchMode": true,
 
   /**
    * (UNDER DEVELOPMENT) The Rush alerts feature provides a way to send announcements to engineers

common/config/rush/nonbrowser-approved-packages.json

@@ -382,6 +382,10 @@
       "name": "@rushstack/rush-sdk",
       "allowedCategories": [ "libraries", "tests", "vscode-extensions" ]
     },
+    {
+      "name": "@rushstack/rush-serve-plugin",
+      "allowedCategories": [ "libraries" ]
+    },
     {
       "name": "@rushstack/set-webpack-public-path-plugin",
       "allowedCategories": [ "libraries", "tests" ]