[rush-lib] Abstract rush publish from npm only and introduce pluggable publish provider

.gitignore

@@ -137,3 +137,6 @@ test-results/
 # Claude Code local configuration
 .claude/*.local.json
 
+# Atomic Workflow plugin artifacts
+specs/
+research/

.mcp.json

@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "deepwiki": {
+      "type": "http",
+      "url": "https://mcp.deepwiki.com/mcp"
+    }
+  }
+}

apps/rush/package.json

@@ -48,6 +48,8 @@
     "@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-npm-publish-plugin": "workspace:*",
+    "@rushstack/rush-vscode-publish-plugin": "workspace:*",
     "@types/heft-jest": "1.0.1",
     "@types/semver": "7.5.0"
   }

apps/rush/src/start-dev.ts

@@ -31,6 +31,8 @@ includePlugin('rush-azure-storage-build-cache-plugin');
 includePlugin('rush-http-build-cache-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');
+includePlugin('rush-npm-publish-plugin');
+includePlugin('rush-vscode-publish-plugin');
 
 const currentPackageVersion: string = PackageJsonLookup.loadOwnPackageJson(__dirname).version;
 RushCommandSelector.execute(currentPackageVersion, rushLib, {

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

@@ -799,6 +799,44 @@ export type _IProjectBuildCacheOptions = _IOperationBuildCacheOptions & {
     phaseName: string;
 };
 
+// @beta
+export interface IPublishCommand extends IRushCommand {
+    readonly dryRun: boolean;
+}
+
+// @public
+export interface IPublishProjectInfo {
+    // Warning: (ae-forgotten-export) The symbol "ChangeType" needs to be exported by the entry point index.d.ts
+    readonly changeType: ChangeType;
+    readonly newVersion: string;
+    readonly previousVersion: string;
+    readonly project: RushConfigurationProject;
+    readonly providerConfig: Record<string, unknown> | undefined;
+}
+
+// @public
+export interface IPublishProvider {
+    checkExistsAsync(options: IPublishProviderCheckExistsOptions): Promise<boolean>;
+    readonly providerName: string;
+    publishAsync(options: IPublishProviderPublishOptions): Promise<void>;
+}
+
+// @public
+export interface IPublishProviderCheckExistsOptions {
+    readonly project: RushConfigurationProject;
+    readonly providerConfig: Record<string, unknown> | undefined;
+    readonly version: string;
+}
+
+// @public
+export interface IPublishProviderPublishOptions {
+    readonly dryRun: boolean;
+    // Warning: (ae-incompatible-release-tags) The symbol "logger" is marked as @public, but its signature references "ILogger" which is marked as @beta
+    readonly logger: ILogger;
+    readonly projects: ReadonlyArray<IPublishProjectInfo>;
+    readonly tag: string | undefined;
+}
+
 // @beta
 export interface IRushCommand {
     readonly actionName: string;
@@ -1202,6 +1240,9 @@ export class ProjectChangeAnalyzer {
     _tryGetSnapshotProviderAsync(projectConfigurations: ReadonlyMap<RushConfigurationProject, RushProjectConfiguration>, terminal: ITerminal, projectSelection?: ReadonlySet<RushConfigurationProject>): Promise<GetInputsSnapshotAsyncFn | undefined>;
 }
 
+// @public
+export type PublishProviderFactory = () => Promise<IPublishProvider>;
+
 // @public
 export class RepoStateFile {
     readonly filePath: string;
@@ -1389,6 +1430,7 @@ export class RushConfigurationProject {
     readonly projectRushConfigFolder: string;
     readonly projectRushTempFolder: string;
     readonly publishFolder: string;
+    get publishTargets(): ReadonlyArray<string>;
     readonly reviewCategory: string | undefined;
     readonly rushConfiguration: RushConfiguration;
     get shouldPublish(): boolean;
@@ -1492,11 +1534,13 @@ export class RushLifecycleHooks {
     subspace: Subspace,
     variant: string | undefined
     ]>;
+    readonly afterPublish: AsyncSeriesHook<[command: IPublishCommand]>;
     readonly beforeInstall: AsyncSeriesHook<[
     command: IGlobalCommand,
     subspace: Subspace,
     variant: string | undefined
     ]>;
+    readonly beforePublish: AsyncSeriesHook<[command: IPublishCommand]>;
     readonly flushTelemetry: AsyncParallelHook<[ReadonlyArray<ITelemetryData>]>;
     readonly initialize: AsyncSeriesHook<IRushCommand>;
     readonly runAnyGlobalCustomCommand: AsyncSeriesHook<IGlobalCommand>;
@@ -1536,12 +1580,16 @@ export class RushSession {
     // (undocumented)
     getLogger(name: string): ILogger;
     // (undocumented)
+    getPublishProviderFactory(publishTargetName: string): PublishProviderFactory | undefined;
+    // (undocumented)
     readonly hooks: RushLifecycleHooks;
     // (undocumented)
     registerCloudBuildCacheProviderFactory(cacheProviderName: string, factory: CloudBuildCacheProviderFactory): void;
     // (undocumented)
     registerCobuildLockProviderFactory(cobuildLockProviderName: string, factory: CobuildLockProviderFactory): void;
     // (undocumented)
+    registerPublishProviderFactory(publishTargetName: string, factory: PublishProviderFactory): void;
+    // (undocumented)
     get terminalProvider(): ITerminalProvider;
 }
 

libraries/rush-lib/package.json

@@ -93,7 +93,9 @@
   "publishOnlyDependencies": {
     "@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-http-build-cache-plugin": "workspace:*",
+    "@rushstack/rush-npm-publish-plugin": "workspace:*",
+    "@rushstack/rush-vscode-publish-plugin": "workspace:*"
   },
   "sideEffects": [
     "lib-esnext/start-pnpm.js",

libraries/rush-lib/scripts/plugins-prepublish.js

@@ -8,5 +8,7 @@ delete packageJson['publishOnlyDependencies'];
 packageJson.dependencies['@rushstack/rush-amazon-s3-build-cache-plugin'] = packageJson.version;
 packageJson.dependencies['@rushstack/rush-azure-storage-build-cache-plugin'] = packageJson.version;
 packageJson.dependencies['@rushstack/rush-http-build-cache-plugin'] = packageJson.version;
+packageJson.dependencies['@rushstack/rush-npm-publish-plugin'] = packageJson.version;
+packageJson.dependencies['@rushstack/rush-vscode-publish-plugin'] = packageJson.version;
 
 JsonFile.save(packageJson, packageJsonPath, { updateExistingFile: true });

libraries/rush-lib/src/api/PublishConfiguration.ts

@@ -0,0 +1,53 @@
+// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.
+// See LICENSE in the project root for license information.
+
+import { ProjectConfigurationFile, InheritanceType } from '@rushstack/heft-config-file';
+
+import publishSchemaJson from '../schemas/publish.schema.json';
+
+/**
+ * Represents the parsed contents of a project's `config/publish.json` file.
+ * @public
+ */
+export interface IPublishJson {
+  /**
+   * An object whose keys are publish target names (e.g. 'npm', 'vsix') and whose
+   * values are provider-specific configuration objects.
+   */
+  providers?: Record<string, Record<string, unknown>>;
+}
+
+/**
+ * The `ProjectConfigurationFile` instance for loading `config/publish.json` with
+ * rig resolution and property inheritance.
+ *
+ * @remarks
+ * The `providers` property uses custom inheritance: child provider sections are
+ * shallow-merged over parent provider sections. This means a project can override
+ * specific provider configs from a rig while inheriting others.
+ *
+ * @internal
+ */
+export const PUBLISH_CONFIGURATION_FILE: ProjectConfigurationFile<IPublishJson> =
+  new ProjectConfigurationFile<IPublishJson>({
+    projectRelativeFilePath: 'config/publish.json',
+    jsonSchemaObject: publishSchemaJson,
+    propertyInheritance: {
+      providers: {
+        inheritanceType: InheritanceType.custom,
+        inheritanceFunction: (
+          child: Record<string, Record<string, unknown>> | undefined,
+          parent: Record<string, Record<string, unknown>> | undefined
+        ): Record<string, Record<string, unknown>> | undefined => {
+          if (!child) {
+            return parent;
+          }
+          if (!parent) {
+            return child;
+          }
+          // Shallow merge: child provider sections override parent provider sections
+          return { ...parent, ...child };
+        }
+      }
+    }
+  });

libraries/rush-lib/src/api/RushConfigurationProject.ts

@@ -27,6 +27,7 @@ export interface IRushConfigurationProjectJson {
   cyclicDependencyProjects?: string[];
   versionPolicyName?: string;
   shouldPublish?: boolean;
+  publishTarget?: string | string[];
   skipRushCheck?: boolean;
   publishFolder?: string;
   tags?: string[];
@@ -67,6 +68,7 @@ export interface IRushConfigurationProjectOptions {
  */
 export class RushConfigurationProject {
   private readonly _shouldPublish: boolean;
+  private readonly _publishTargets: ReadonlyArray<string>;
 
   private _versionPolicy: VersionPolicy | undefined = undefined;
   private _dependencyProjects: Set<RushConfigurationProject> | undefined = undefined;
@@ -328,10 +330,47 @@ export class RushConfigurationProject {
     this.skipRushCheck = !!projectJson.skipRushCheck;
     this.versionPolicyName = projectJson.versionPolicyName;
 
-    if (this._shouldPublish && this.packageJson.private) {
+    // Normalize publishTarget: string -> [string], undefined -> ['npm']
+    const rawTarget: string | string[] | undefined = projectJson.publishTarget;
+    if (rawTarget === undefined) {
+      this._publishTargets = ['npm'];
+    } else if (typeof rawTarget === 'string') {
+      this._publishTargets = [rawTarget];
+    } else {
+      this._publishTargets = rawTarget;
+    }
+
+    // Validate: 'none' cannot be combined with other targets
+    if (this._publishTargets.includes('none') && this._publishTargets.length > 1) {
       throw new Error(
-        `The project "${packageName}" specifies "shouldPublish": true, ` +
-          `but the package.json file specifies "private": true.`
+        `The project "${packageName}" specifies publishTarget "none" combined with other targets. ` +
+          `The "none" target cannot be combined with other publish targets.`
+      );
+    }
+
+    // Validate: 'none' is incompatible with lockstep version policies
+    if (
+      this._publishTargets.includes('none') &&
+      this.versionPolicyName &&
+      rushConfiguration.versionPolicyConfiguration
+    ) {
+      const policy: VersionPolicy | undefined = rushConfiguration.versionPolicyConfiguration.getVersionPolicy(
+        this.versionPolicyName
+      );
+      if (policy && policy.isLockstepped) {
+        throw new Error(
+          `The project "${packageName}" specifies publishTarget "none" but uses the lockstep ` +
+            `version policy "${this.versionPolicyName}". The "none" target is incompatible with ` +
+            `lockstep version policies.`
+        );
+      }
+    }
+
+    // Validate: private:true is only invalid when publishTargets includes 'npm'
+    if (this._shouldPublish && this.packageJson.private && this._publishTargets.includes('npm')) {
+      throw new Error(
+        `The project "${packageName}" specifies "shouldPublish": true with ` +
+          `publishTarget including "npm", but the package.json file specifies "private": true.`
       );
     }
 
@@ -482,6 +521,21 @@ export class RushConfigurationProject {
     return this._shouldPublish || !!this.versionPolicyName;
   }
 
+  /**
+   * Specifies the publish targets for this project. Determines which publish
+   * provider plugins handle publishing during `rush publish`.
+   *
+   * @remarks
+   * Common values: `'npm'`, `'vsix'`, `'none'`.
+   * When the array contains `'none'`, the project participates in versioning
+   * but is not published by any provider.
+   * When omitted in rush.json, defaults to `['npm']` for backward compatibility.
+   * A string value is normalized to a single-element array.
+   */
+  public get publishTargets(): ReadonlyArray<string> {
+    return this._publishTargets;
+  }
+
   /**
    * Version policy of the project
    * @beta