@rushstack/rush-sdk 5.170.0 → 5.170.1-pr5378.0

package/lib-commonjs/index.js

@@ -25,6 +25,7 @@ exports.LockStepVersionPolicy = _m.LockStepVersionPolicy;
 exports.LookupByPath = _m.LookupByPath;
 exports.NpmOptionsConfiguration = _m.NpmOptionsConfiguration;
 exports.Operation = _m.Operation;
+exports.OperationGraphHooks = _m.OperationGraphHooks;
 exports.OperationStatus = _m.OperationStatus;
 exports.PackageJsonDependency = _m.PackageJsonDependency;
 exports.PackageJsonDependencyMeta = _m.PackageJsonDependencyMeta;

package/lib-commonjs/logic/operations/IOperationGraph.js

@@ -0,0 +1,2 @@
+const _m = require("../../../lib-shim/index.js")._rushSdk_loadInternalModule("logic/operations/IOperationGraph");
+module.exports = _m;

package/lib-commonjs/logic/operations/OperationGraph.js

@@ -0,0 +1,3 @@
+const _m = require("../../../lib-shim/index.js")._rushSdk_loadInternalModule("logic/operations/OperationGraph");
+module.exports = _m;
+exports.OperationGraph = _m.OperationGraph;

package/lib-commonjs/logic/operations/OperationStatus.js

@@ -1,4 +1,5 @@
 const _m = require("../../../lib-shim/index.js")._rushSdk_loadInternalModule("logic/operations/OperationStatus");
 module.exports = _m;
 exports.OperationStatus = _m.OperationStatus;
+exports.SUCCESS_STATUSES = _m.SUCCESS_STATUSES;
 exports.TERMINAL_STATUSES = _m.TERMINAL_STATUSES;

package/lib-commonjs/{cli/parsing → logic/operations}/ParseParallelism.js

@@ -1,5 +1,6 @@
-const _m = require("../../../lib-shim/index.js")._rushSdk_loadInternalModule("cli/parsing/ParseParallelism");
+const _m = require("../../../lib-shim/index.js")._rushSdk_loadInternalModule("logic/operations/ParseParallelism");
 module.exports = _m;
+exports.coerceParallelism = _m.coerceParallelism;
 exports.getNumberOfCores = _m.getNumberOfCores;
 exports.parseParallelism = _m.parseParallelism;
 exports.parseParallelismPercent = _m.parseParallelismPercent;

package/lib-commonjs/pluginFramework/OperationGraphHooks.js

@@ -0,0 +1,3 @@
+const _m = require("../../lib-shim/index.js")._rushSdk_loadInternalModule("pluginFramework/OperationGraphHooks");
+module.exports = _m;
+exports.OperationGraphHooks = _m.OperationGraphHooks;

package/lib-dts/api/CommandLineConfiguration.d.ts

@@ -85,6 +85,13 @@ export interface IPhasedCommandConfig extends IPhasedCommandWithoutPhasesJson, I
      * How many milliseconds to wait after receiving a file system notification before executing in watch mode.
      */
     watchDebounceMs?: number;
+    /**
+     * If true, when running this command in watch mode the operation graph will include every project
+     * in the repository (respecting phase selection), but only the projects selected by the user's
+     * CLI project selection parameters will be initially enabled. Other projects will remain disabled
+     * unless they become required or are explicitly selected in a subsequent pass.
+     */
+    includeAllProjectsInWatchGraph?: boolean;
     /**
      * If set to `true`, then this phased command will always perform an install before executing, regardless of CLI flags.
      * If set to `false`, then Rush will define a built-in "--install" CLI flag for this command.

package/lib-dts/api/CommandLineJson.d.ts

@@ -46,6 +46,7 @@ export interface IPhasedCommandJson extends IPhasedCommandWithoutPhasesJson {
         alwaysWatch: boolean;
         debounceMs?: number;
         watchPhases: string[];
+        includeAllProjectsInWatchGraph?: boolean;
     };
     installOptions?: {
         alwaysInstall: boolean;

package/lib-dts/api/EnvironmentConfiguration.d.ts

@@ -211,6 +211,12 @@ export declare const EnvironmentVariableNames: {
      * if Rush did not explicitly pass along command-line parameters to their process.
      */
     readonly RUSH_INVOKED_ARGS: "RUSH_INVOKED_ARGS";
+    /**
+     * When set to `1` or `true`, this environment variable is equivalent to passing the `--quiet` flag
+     * to `rush`, `rushx`, and `install-run-rush.ts`. It suppresses informational startup messages
+     * while preserving error output.
+     */
+    readonly RUSH_QUIET_MODE: "RUSH_QUIET_MODE";
 };
 /**
  * Provides Rush-specific environment variable data. All Rush environment variables must start with "RUSH_". This class
@@ -239,6 +245,7 @@ export declare class EnvironmentConfiguration {
     private static _cobuildLeafProjectLogOnlyAllowed;
     private static _gitBinaryPath;
     private static _tarBinaryPath;
+    private static _quietMode;
     /**
      * If true, the environment configuration has been validated and initialized.
      */
@@ -331,6 +338,11 @@ export declare class EnvironmentConfiguration {
      * See {@link EnvironmentVariableNames.RUSH_TAR_BINARY_PATH}
      */
     static get tarBinaryPath(): string | undefined;
+    /**
+     * If `true`, Rush will suppress informational startup messages, equivalent to passing `--quiet`.
+     * See {@link EnvironmentVariableNames.RUSH_QUIET_MODE}
+     */
+    static get quietMode(): boolean;
     /**
      * The front-end RushVersionSelector relies on `RUSH_GLOBAL_FOLDER`, so its value must be read before
      * `EnvironmentConfiguration` is initialized (and actually before the correct version of `EnvironmentConfiguration`

package/lib-dts/api/EventHooks.d.ts

@@ -1,6 +1,6 @@
 import type { IEventHooksJson } from './RushConfiguration';
 /**
- * Events happen during Rush runs.
+ * Events happen during Rush invocation.
  * @beta
  */
 export declare enum Event {

package/lib-dts/cli/parsing/SelectionParameterSet.d.ts

@@ -46,7 +46,7 @@ export declare class SelectionParameterSet {
      *
      * If no parameters are specified, returns all projects in the Rush config file.
      */
-    getSelectedProjectsAsync(terminal: ITerminal): Promise<Set<RushConfigurationProject>>;
+    getSelectedProjectsAsync(terminal: ITerminal, allowEmptySelection?: boolean): Promise<Set<RushConfigurationProject>>;
     /**
      * Represents the selection as `--filter` parameters to pnpm.
      *

package/lib-dts/cli/scriptActions/PhasedScriptAction.d.ts

@@ -13,6 +13,7 @@ export interface IPhasedScriptActionOptions extends IBaseScriptActionOptions<IPh
     originalPhases: Set<IPhase>;
     initialPhases: Set<IPhase>;
     watchPhases: Set<IPhase>;
+    includeAllProjectsInWatchGraph: boolean;
     phases: Map<string, IPhase>;
     alwaysWatch: boolean;
     alwaysInstall: boolean | undefined;
@@ -44,10 +45,9 @@ export declare class PhasedScriptAction extends BaseScriptAction<IPhasedCommandC
     private readonly _watchDebounceMs;
     private readonly _alwaysWatch;
     private readonly _alwaysInstall;
+    private readonly _includeAllProjectsInWatchGraph;
     private readonly _knownPhases;
     private readonly _terminal;
-    private _changedProjectsOnly;
-    private _executionAbortController;
     private readonly _changedProjectsOnlyParameter;
     private readonly _selectionParameters;
     private readonly _verboseParameter;
@@ -64,16 +64,6 @@ export declare class PhasedScriptAction extends BaseScriptAction<IPhasedCommandC
     private readonly _includePhaseDeps;
     constructor(options: IPhasedScriptActionOptions);
     runAsync(): Promise<void>;
-    private _runInitialPhasesAsync;
-    private _registerWatchModeInterface;
-    /**
-     * Runs the command in watch mode. Fundamentally is a simple loop:
-     * 1) Wait for a change to one or more projects in the selection
-     * 2) Invoke the command on the changed projects, and, if applicable, impacted projects
-     *    Uses the same algorithm as --impacted-by
-     * 3) Goto (1)
-     */
-    private _runWatchPhasesAsync;
     /**
      * Runs a set of operations and reports the results.
      */

package/lib-dts/index.d.ts

@@ -40,14 +40,17 @@ export { ExperimentsConfiguration, type IExperimentsJson } from './api/Experimen
 export { CustomTipsConfiguration, CustomTipId, type ICustomTipsJson, type ICustomTipInfo, type ICustomTipItemJson, CustomTipSeverity, CustomTipType } from './api/CustomTipsConfiguration';
 export { ProjectChangeAnalyzer, type IGetChangedProjectsOptions } from './logic/ProjectChangeAnalyzer';
 export type { IInputsSnapshot, GetInputsSnapshotAsyncFn as GetInputsSnapshotAsyncFn, IRushConfigurationProjectForSnapshot } from './logic/incremental/InputsSnapshot';
-export type { IOperationRunner, IOperationRunnerContext } from './logic/operations/IOperationRunner';
-export type { IExecutionResult, IOperationExecutionResult } from './logic/operations/IOperationExecutionResult';
-export { type IOperationOptions, Operation } from './logic/operations/Operation';
+export type { IOperationRunner, IOperationRunnerContext, IOperationLastState } from './logic/operations/IOperationRunner';
+export type { IConfigurableOperation, IBaseOperationExecutionResult, IExecutionResult, IOperationExecutionResult, IOperationStateHashComponents } from './logic/operations/IOperationExecutionResult';
+export { type IOperationOptions, type OperationEnabledState, Operation } from './logic/operations/Operation';
+export { type IParallelismScalar, type Parallelism } from './logic/operations/ParseParallelism';
 export { OperationStatus } from './logic/operations/OperationStatus';
 export type { ILogFilePaths } from './logic/operations/ProjectLogWritable';
 export { RushSession, type IRushSessionOptions, type CloudBuildCacheProviderFactory, type CobuildLockProviderFactory } from './pluginFramework/RushSession';
 export { type IRushCommand, type IGlobalCommand, type IPhasedCommand, RushLifecycleHooks } from './pluginFramework/RushLifeCycle';
-export { type ICreateOperationsContext, type IExecuteOperationsContext, PhasedCommandHooks } from './pluginFramework/PhasedCommandHooks';
+export { type ICreateOperationsContext, type IOperationGraphContext, type IPhasedCommandPlugin, PhasedCommandHooks } from './pluginFramework/PhasedCommandHooks';
+export type { IOperationGraph, IOperationGraphIterationOptions } from './logic/operations/IOperationGraph';
+export { OperationGraphHooks } from './pluginFramework/OperationGraphHooks';
 export type { IRushPlugin } from './pluginFramework/IRushPlugin';
 export type { IBuiltInPluginConfiguration as _IBuiltInPluginConfiguration } from './pluginFramework/PluginLoader/BuiltInPluginLoader';
 export type { IRushPluginConfigurationBase as _IRushPluginConfigurationBase } from './api/RushPluginsConfiguration';

package/lib-dts/logic/ProjectWatcher.d.ts

@@ -1,15 +1,15 @@
 import { type ITerminal } from '@rushstack/terminal';
-import type { IInputsSnapshot, GetInputsSnapshotAsyncFn } from './incremental/InputsSnapshot';
+import type { IInputsSnapshot } from './incremental/InputsSnapshot';
 import type { RushConfiguration } from '../api/RushConfiguration';
 import type { RushConfigurationProject } from '../api/RushConfigurationProject';
+import type { IOperationGraph } from './operations/IOperationGraph';
 export interface IProjectWatcherOptions {
-    abortSignal: AbortSignal;
-    getInputsSnapshotAsync: GetInputsSnapshotAsyncFn;
-    debounceMs?: number;
+    graph: IOperationGraph;
+    debounceMs: number;
     rushConfiguration: RushConfiguration;
-    projectsToWatch: ReadonlySet<RushConfigurationProject>;
     terminal: ITerminal;
-    initialSnapshot?: IInputsSnapshot | undefined;
+    /** Initial inputs snapshot; required so watcher can enumerate nested folders immediately */
+    initialSnapshot: IInputsSnapshot;
 }
 export interface IProjectChangeResult {
     /**
@@ -25,59 +25,81 @@ export interface IPromptGeneratorFunction {
     (isPaused: boolean): Iterable<string>;
 }
 /**
- * This class is for incrementally watching a set of projects in the repository for changes.
+ * Watches a set of projects in the repository for file changes and triggers
+ * rebuild iterations on the operation graph.
  *
- * We are manually using fs.watch() instead of `chokidar` because all we want from the file system watcher is a boolean
- * signal indicating that "at least 1 file in a watched project changed". We then defer to getInputsSnapshotAsync (which
- * is responsible for change detection in all incremental builds) to determine what actually chanaged.
- *
- * Calling `waitForChange()` will return a promise that resolves when the package-deps of one or
- * more projects differ from the value the previous time it was invoked. The first time will always resolve with the full selection.
+ * Uses `fs.watch()` rather than `chokidar` because only a boolean "something changed"
+ * signal is needed; actual change detection is deferred to `getInputsSnapshotAsync`.
  */
 export declare class ProjectWatcher {
-    private readonly _abortSignal;
-    private readonly _getInputsSnapshotAsync;
     private readonly _debounceMs;
-    private readonly _repoRoot;
     private readonly _rushConfiguration;
-    private readonly _projectsToWatch;
     private readonly _terminal;
-    private _initialSnapshot;
-    private _previousSnapshot;
-    private _forceChangedProjects;
-    private _resolveIfChanged;
-    private _onAbort;
-    private _getPromptLines;
+    private readonly _graph;
+    private _repoRoot;
+    private _watchers;
+    private _closePromises;
+    private _debounceHandle;
+    private _isWatching;
     private _lastStatus;
     private _renderedStatusLines;
-    isPaused: boolean;
+    private _lastSnapshot;
+    private _stdinListening;
+    private _stdinHadRawMode;
+    private _onStdinDataBound;
     constructor(options: IProjectWatcherOptions);
-    pause(): void;
-    resume(): void;
-    invalidateProject(project: RushConfigurationProject, reason: string): boolean;
-    invalidateAll(reason: string): void;
+    /**
+     * Resets the rendered line count so the next status update does not attempt
+     * to overwrite previously rendered lines.
+     */
     clearStatus(): void;
+    /**
+     * Re-renders the most recent status line (or a default) in place.
+     */
     rerenderStatus(): void;
-    setPromptGenerator(promptGenerator: IPromptGeneratorFunction): void;
     /**
-     * Waits for a change to the package-deps of one or more of the selected projects, since the previous invocation.
-     * Will return immediately the first time it is invoked, since no state has been recorded.
-     * If no change is currently present, watches the source tree of all selected projects for file changes.
-     * `waitForChange` is not allowed to be called multiple times concurrently.
+     * Renders the given status message to the terminal, preceded by mode indicators
+     * and keybind help when stdin is active. Overwrites previously rendered status lines
+     * when not mid-execution.
      */
-    waitForChangeAsync(onWatchingFiles?: () => void): Promise<IProjectChangeResult>;
     private _setStatus;
     /**
-     * Determines which, if any, projects (within the selection) have new hashes for files that are not in .gitignore
+     * Begins watching the file system for changes in all tracked project folders.
+     * On platforms without native recursive watch support (Linux), enumerates nested
+     * folders from the last snapshot to set up individual watchers.
+     */
+    private _startWatching;
+    /**
+     * Closes all active file system watchers and waits for their close events to settle.
+     */
+    private _stopWatchingAsync;
+    /**
+     * Handles a raw file system event by debouncing and scheduling an iteration.
+     * Ignores changes to `.git` and `node_modules`.
+     */
+    private _onFsEvent;
+    /**
+     * Schedules a new execution iteration on the graph in response to detected file changes.
+     */
+    private _scheduleIteration;
+    /**
+     * Sets up a raw-mode stdin listener so the user can interact with the watch session
+     * via single-key keybinds. Captures the previous raw-mode state for restoration on dispose.
+     */
+    private _ensureStdin;
+    /**
+     * Removes the stdin listener and restores the previous raw-mode state.
+     */
+    private _disposeStdin;
+    /**
+     * Processes a chunk of stdin data, dispatching each character to the appropriate
+     * keybind action on the operation graph.
      */
-    private _computeChangedAsync;
-    private _commitChanges;
+    private _onStdinData;
     /**
-     * Tests for inequality of the passed Maps. Order invariant.
-     *
-     * @returns `true` if the maps are different, `false` otherwise
+     * Adjusts the parallelism on the operation graph by the given delta
+     * and reports the result.
      */
-    private static _haveProjectDepsChanged;
-    private static _enumeratePathsToWatch;
+    private _adjustParallelism;
 }
 //# sourceMappingURL=ProjectWatcher.d.ts.map

package/lib-dts/logic/buildCache/OperationBuildCache.d.ts

@@ -1,7 +1,7 @@
 import type { ITerminal } from '@rushstack/terminal';
 import type { RushConfigurationProject } from '../../api/RushConfigurationProject';
 import type { BuildCacheConfiguration } from '../../api/BuildCacheConfiguration';
-import type { IOperationExecutionResult } from '../operations/IOperationExecutionResult';
+import type { IBaseOperationExecutionResult } from '../operations/IOperationExecutionResult';
 /**
  * @internal
  */
@@ -58,7 +58,7 @@ export declare class OperationBuildCache {
     private static _tryGetTarUtility;
     get cacheId(): string | undefined;
     static getOperationBuildCache(options: IProjectBuildCacheOptions): OperationBuildCache;
-    static forOperation(executionResult: IOperationExecutionResult, options: IOperationBuildCacheOptions): OperationBuildCache;
+    static forOperation(executionResult: IBaseOperationExecutionResult, options: IOperationBuildCacheOptions): OperationBuildCache;
     tryRestoreFromCacheAsync(terminal: ITerminal, specifiedCacheId?: string): Promise<boolean>;
     trySetCacheEntryAsync(terminal: ITerminal, specifiedCacheId?: string): Promise<boolean>;
     /**

package/lib-dts/logic/operations/IOperationExecutionResult.d.ts

@@ -1,17 +1,68 @@
 import type { StdioSummarizer, IProblemCollector } from '@rushstack/terminal';
 import type { OperationStatus } from './OperationStatus';
+import type { IOperationLastState } from './IOperationRunner';
 import type { Operation } from './Operation';
 import type { IStopwatchResult } from '../../utilities/Stopwatch';
 import type { ILogFilePaths } from './ProjectLogWritable';
 /**
- * The `IOperationExecutionResult` interface represents the results of executing an {@link Operation}.
+ * Structured components of the state hash for an operation.
+ * @alpha
+ */
+export interface IOperationStateHashComponents {
+    /**
+     * The state hashes of operation dependencies, sorted by name.
+     * Each entry is of the form `{dependencyName}={hash}`.
+     */
+    readonly dependencies: readonly string[];
+    /**
+     * The hash of the operation's own local inputs (e.g. tracked files, environment variables).
+     */
+    readonly local: string;
+    /**
+     * The hash of the operation's configuration (e.g. CLI parameters).
+     */
+    readonly config: string;
+}
+/**
  * @alpha
  */
-export interface IOperationExecutionResult {
+export interface IBaseOperationExecutionResult {
     /**
      * The operation itself
      */
     readonly operation: Operation;
+    /**
+     * The relative path to the folder that contains operation metadata. This folder will be automatically included in cache entries.
+     */
+    readonly metadataFolderPath: string;
+    /**
+     * Gets the hash of the state of all registered inputs to this operation.
+     * Calling this method will throw if Git is not available.
+     */
+    getStateHash(): string;
+    /**
+     * Gets the structured components of the state hash. This is useful for debugging and
+     * incremental change detection.
+     * Calling this method will throw if Git is not available.
+     */
+    getStateHashComponents(): IOperationStateHashComponents;
+}
+/**
+ * The `IConfigurableOperation` interface represents an {@link Operation} whose
+ * execution can be configured before running.
+ * @alpha
+ */
+export interface IConfigurableOperation extends IBaseOperationExecutionResult {
+    /**
+     * True if the operation should execute in this iteration, false otherwise.
+     */
+    enabled: boolean;
+}
+/**
+ * The `IOperationExecutionResult` interface represents the results of executing an {@link Operation}.
+ * @alpha
+ */
+export interface IOperationExecutionResult extends IBaseOperationExecutionResult, IOperationLastState {
     /**
      * The current execution status of an operation. Operations start in the 'ready' state,
      * but can be 'blocked' if an upstream operation failed. It is 'executing' when
@@ -28,6 +79,10 @@ export interface IOperationExecutionResult {
      * If this operation is only present in the graph to maintain dependency relationships, this flag will be set to true.
      */
     readonly silent: boolean;
+    /**
+     * True if the operation should execute in this iteration, false otherwise.
+     */
+    readonly enabled: boolean;
     /**
      * Object tracking execution timing.
      */
@@ -44,24 +99,10 @@ export interface IOperationExecutionResult {
      * The value indicates the duration of the same operation without cache hit.
      */
     readonly nonCachedDurationMs: number | undefined;
-    /**
-     * The relative path to the folder that contains operation metadata. This folder will be automatically included in cache entries.
-     */
-    readonly metadataFolderPath: string | undefined;
     /**
      * The paths to the log files, if applicable.
      */
     readonly logFilePaths: ILogFilePaths | undefined;
-    /**
-     * Gets the hash of the state of all registered inputs to this operation.
-     * Calling this method will throw if Git is not available.
-     */
-    getStateHash(): string;
-    /**
-     * Gets the components of the state hash. This is useful for debugging purposes.
-     * Calling this method will throw if Git is not available.
-     */
-    getStateHashComponents(): ReadonlyArray<string>;
 }
 /**
  * The `IExecutionResult` interface represents the results of executing a set of {@link Operation}s.

package/lib-dts/logic/operations/IOperationGraph.d.ts

@@ -0,0 +1,137 @@
+import type { TerminalWritable } from '@rushstack/terminal';
+import type { Operation } from './Operation';
+import type { IOperationExecutionResult } from './IOperationExecutionResult';
+import type { Parallelism } from './ParseParallelism';
+import type { OperationStatus } from './OperationStatus';
+import type { IInputsSnapshot } from '../incremental/InputsSnapshot';
+import type { OperationGraphHooks } from '../../pluginFramework/OperationGraphHooks';
+/**
+ * Options for a single iteration of operation execution.
+ * @alpha
+ */
+export interface IOperationGraphIterationOptions {
+    inputsSnapshot?: IInputsSnapshot;
+    /**
+     * The time when the iteration was scheduled, if available, as returned by `performance.now()`.
+     */
+    startTime?: number;
+}
+/**
+ * Public API for the operation graph.
+ * @alpha
+ */
+export interface IOperationGraph {
+    /**
+     * Hooks into the execution process for operations
+     */
+    readonly hooks: OperationGraphHooks;
+    /**
+     * The set of operations in the graph.
+     */
+    readonly operations: ReadonlySet<Operation>;
+    /**
+     * A map from each `Operation` in the graph to its current result record.
+     * The map is updated in real time as operations execute during an iteration.
+     * Only statuses representing a completed execution (e.g. `Success`, `Failure`,
+     * `SuccessWithWarning`) write to this map; statuses such as `Skipped` or `Aborted` —
+     * which indicate that an operation did not actually run — do not update it.
+     * For operations that have not yet run in the current iteration, the map retains the
+     * result from whichever prior iteration the operation last ran in.
+     * An entry with status `Ready` indicates that the operation is considered stale and
+     * has been queued to run again.
+     * Empty until at least one operation has completed execution.
+     */
+    readonly resultByOperation: ReadonlyMap<Operation, IOperationExecutionResult>;
+    /**
+     * The maximum allowed parallelism for this operation graph.
+     * Reads as a concrete integer. Accepts a `Parallelism` value and coerces it on write.
+     */
+    get parallelism(): number;
+    set parallelism(value: Parallelism);
+    /**
+     * If additional debug information should be printed during execution.
+     */
+    debugMode: boolean;
+    /**
+     * If true, operations will be executed in "quiet mode" where only errors are reported.
+     */
+    quietMode: boolean;
+    /**
+     * If true, allow operations to oversubscribe the CPU. Defaults to true.
+     */
+    allowOversubscription: boolean;
+    /**
+     * When true, the operation graph will pause before running the next iteration (manual mode).
+     * When false, iterations run automatically when scheduled.
+     */
+    pauseNextIteration: boolean;
+    /**
+     * The current overall status of the execution.
+     */
+    readonly status: OperationStatus;
+    /**
+     * The current set of terminal destinations.
+     */
+    readonly terminalDestinations: ReadonlySet<TerminalWritable>;
+    /**
+     * True if there is a scheduled (but not yet executing) iteration.
+     * This will be false while an iteration is actively executing, or when no work is scheduled.
+     */
+    readonly hasScheduledIteration: boolean;
+    /**
+     * AbortController controlling the lifetime of the overall session (e.g. watch mode).
+     * Aborting this controller should signal all listeners (such as file system watchers) to dispose
+     * and prevent further iterations from being scheduled.
+     */
+    readonly abortController: AbortController;
+    /**
+     * Abort the current execution iteration, if any. Operations that have already started
+     * will run to completion; only operations that have not yet begun will be aborted.
+     */
+    abortCurrentIterationAsync(): Promise<void>;
+    /**
+     * Cleans up any resources used by the operation runners, if applicable.
+     * @param operations - The operations whose runners should be closed, or undefined to close all runners.
+     */
+    closeRunnersAsync(operations?: Iterable<Operation>): Promise<void>;
+    /**
+     * Executes a single iteration of the operations.
+     * @param options - Options for this execution iteration.
+     * @returns A promise that resolves to true if the iteration has work to be done, or false if the iteration was empty and therefore not scheduled.
+     */
+    scheduleIterationAsync(options: IOperationGraphIterationOptions): Promise<boolean>;
+    /**
+     * Executes all operations in the currently scheduled iteration, if any.
+     * @returns A promise which is resolved when all operations have been processed to a final state.
+     */
+    executeScheduledIterationAsync(): Promise<boolean>;
+    /**
+     * Invalidates the specified operations, causing them to be re-executed.
+     * @param operations - The operations to invalidate, or undefined to invalidate all operations.
+     * @param reason - Optional reason for invalidation.
+     */
+    invalidateOperations(operations?: Iterable<Operation>, reason?: string): void;
+    /**
+     * Sets the enabled state for a collection of operations.
+     *
+     * @param operations - The operations whose enabled state should be updated.
+     * @param targetState - The target enabled state to apply.
+     * @param mode - 'unsafe' to directly mutate only the provided operations, 'safe' to also enable
+     * transitive dependencies of enabled operations and disable transitive dependents of disabled operations.
+     * @returns true if any operation's enabled state changed, false otherwise.
+     */
+    setEnabledStates(operations: Iterable<Operation>, targetState: Operation['enabled'], mode: 'safe' | 'unsafe'): boolean;
+    /**
+     * Adds a terminal destination for output. Only new output will be sent to the destination.
+     * @param destination - The destination to add.
+     */
+    addTerminalDestination(destination: TerminalWritable): void;
+    /**
+     * Removes a terminal destination for output. Optionally closes the stream.
+     * New output will no longer be sent to the destination.
+     * @param destination - The destination to remove.
+     * @param close - Whether to close the stream. Defaults to `true`.
+     */
+    removeTerminalDestination(destination: TerminalWritable, close?: boolean): boolean;
+}
+//# sourceMappingURL=IOperationGraph.d.ts.map

package/lib-dts/logic/operations/IOperationRunner.d.ts

@@ -4,6 +4,17 @@ import type { OperationStatus } from './OperationStatus';
 import type { OperationMetadataManager } from './OperationMetadataManager';
 import type { IStopwatchResult } from '../../utilities/Stopwatch';
 import type { IEnvironment } from '../../utilities/Utilities';
+/**
+ * A snapshot of a previous operation execution, passed to runners to inform incremental behavior.
+ *
+ * @beta
+ */
+export interface IOperationLastState {
+    /**
+     * The status from the previous execution of this operation.
+     */
+    readonly status: OperationStatus;
+}
 /**
  * Information passed to the executing `IOperationRunner`
  *
@@ -49,6 +60,12 @@ export interface IOperationRunnerContext {
      * it later (for example to re-print errors at end of execution).
      */
     error?: Error;
+    /**
+     * Returns a callback that invalidates this operation so that it will be re-executed in the next iteration.
+     * The returned callback captures only the minimal state needed, avoiding retention of the full context.
+     * Callers should store the result rather than calling this method repeatedly.
+     */
+    getInvalidateCallback(): (reason: string) => void;
     /**
      * Invokes the specified callback with a terminal that is associated with this operation.
      *
@@ -61,7 +78,7 @@ export interface IOperationRunnerContext {
 }
 /**
  * The `Operation` class is a node in the dependency graph of work that needs to be scheduled by the
- * `OperationExecutionManager`. Each `Operation` has a `runner` member of type `IOperationRunner`, whose
+ * `OperationGraph`. Each `Operation` has a `runner` member of type `IOperationRunner`, whose
  * implementation manages the actual process for running a single operation.
  *
  * @beta
@@ -93,13 +110,26 @@ export interface IOperationRunner {
      * analysis purposes.
      */
     readonly isNoOp?: boolean;
+    /**
+     * If true, this runner currently owns some kind of active resource (e.g. a service or a watch process).
+     * This can be used to determine if the operation is "in progress" even if it is not currently executing.
+     * If the runner supports this property, it should update it as appropriate during execution.
+     * The property is optional to avoid breaking existing implementations of IOperationRunner.
+     */
+    readonly isActive?: boolean;
     /**
      * Method to be executed for the operation.
+     * @param context - The context object containing information about the execution environment.
+     * @param lastState - The last execution result of this operation, if any.
      */
-    executeAsync(context: IOperationRunnerContext): Promise<OperationStatus>;
+    executeAsync(context: IOperationRunnerContext, lastState?: IOperationLastState): Promise<OperationStatus>;
     /**
      * Return a hash of the configuration that affects the operation.
      */
     getConfigHash(): string;
+    /**
+     * If this runner performs any background work to optimize future runs, this method will clean it up.
+     */
+    closeAsync?(): Promise<void>;
 }
 //# sourceMappingURL=IOperationRunner.d.ts.map