[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"
+    }
+  }
+}

CLAUDE.md

@@ -0,0 +1,95 @@
+# Rush Stack Monorepo
+
+## Overview
+Microsoft's Rush Stack: ~130 TypeScript projects providing the Rush monorepo manager, Heft build system, API Extractor, ESLint configs, webpack plugins, and supporting libraries. Managed by Rush v5 with pnpm.
+
+## Monorepo Structure
+All projects are exactly 2 levels deep (e.g., `apps/rush`, `libraries/node-core-library`).
+
+| Path | Purpose |
+|------|---------|
+| `apps/` | Published CLI tools (Rush, Heft, API Extractor, etc.) |
+| `libraries/` | Core shared libraries |
+| `heft-plugins/` | Heft build system plugins |
+| `rush-plugins/` | Rush monorepo plugins |
+| `webpack/` | Webpack loaders and plugins |
+| `eslint/` | ESLint configs, plugins, patches |
+| `rigs/` | Shared build configurations (rig packages) |
+| `vscode-extensions/` | VS Code extensions |
+| `build-tests/` | Integration/scenario tests (non-shipping) |
+| `build-tests-samples/` | Tutorial sample projects (non-shipping) |
+| `common/` | Rush config, autoinstallers, temp files |
+
+## Quick Reference
+
+### Commands
+```bash
+rush install                    # Install deps (frozen lockfile)
+rush build                      # Incremental build
+rush test                       # Incremental build + test
+rush retest                     # Full rebuild + test (CI uses this)
+rush start                      # Watch mode
+rush build -t <package-name>    # Build single project + its deps
+rush build --to .               # Build project in current directory + deps
+rush prettier                   # Format staged files (pre-commit hook)
+rush change                     # Generate changelog entries for modified packages
+```
+
+### Custom Build Parameters
+- `--production` -- Production build with minification
+- `--fix` -- Auto-fix lint problems
+- `--update-snapshots` -- Update Jest snapshots
+- `--verbose` -- Detailed build output
+
+### Build Phases
+```
+_phase:lite-build  →  _phase:build  →  _phase:test
+(simple builds)       (TS + lint +      (Jest tests)
+                       API Extractor)
+```
+
+## Build System Architecture
+- **Rush**: Monorepo orchestrator (dependency graph, parallelism, build cache)
+- **Heft**: Project-level build system (TypeScript, ESLint, Jest, API Extractor via plugins)
+- **Rig system**: Projects inherit build config via `config/rig.json` pointing to a rig package
+  - Most projects use `local-node-rig` or `decoupled-local-node-rig`
+  - `decoupled-local-node-rig` is for packages that are themselves deps of the build toolchain
+
+## Code Conventions
+- TypeScript strict mode, target ES2017/ES2018, CommonJS output to `lib/`
+- ESLint v9 flat config; per-project `eslint.config.js` composing profiles + mixins from rig
+- Async methods must have `Async` suffix (ESLint naming convention rule)
+- `export * from '...'` is forbidden (use explicit named exports)
+- Tests: `src/test/*.test.ts`, run via Heft/Jest against compiled `lib/` output
+- Prettier: `printWidth: 110`, `singleQuote: true`, `trailingComma: 'none'`
+
+## Verification
+```bash
+rush build -t <package>         # Build the package you changed
+rush test -t <package>          # Build + test the package you changed
+```
+The pre-commit hook runs `rush prettier` automatically on staged files.
+
+## Progressive Disclosure
+| Topic | Location |
+|-------|----------|
+| Rush config | `rush.json`, `common/config/rush/` |
+| Build phases & commands | `common/config/rush/command-line.json` |
+| Build cache | `common/config/rush/build-cache.json` |
+| Version policies | `common/config/rush/version-policies.json` |
+| Node rig (build pipeline) | `rigs/heft-node-rig/profiles/default/config/heft.json` |
+| TypeScript base config | `rigs/heft-node-rig/profiles/default/tsconfig-base.json` |
+| ESLint rules | `rigs/decoupled-local-node-rig/profiles/default/includes/eslint/flat/` |
+| Jest shared config | `heft-plugins/heft-jest-plugin/includes/jest-shared.config.json` |
+| API review files | `common/reviews/api/` |
+| Plugin architecture | `libraries/rush-lib/src/pluginFramework/` |
+| CI pipeline | `.github/workflows/ci.yml` |
+| Contributor guidelines | `.github/PULL_REQUEST_TEMPLATE.md`, rushstack.io |
+| Existing research | `research/docs/` |
+
+## Universal Rules
+1. Run `rush build -t <pkg> && rush test -t <pkg>` to verify changes
+2. Run `rush change` when modifying published packages
+3. Git email must match `*@users.noreply.github.com` (enforced by rush.json git policy)
+4. Rush core packages (`@microsoft/rush`, `rush-lib`, `rush-sdk`, rush-plugins) share a lock-step version
+5. API Extractor reports in `common/reviews/api/` must be updated when public APIs change

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 };
+        }
+      }
+    }
+  });