Add positron.workspace.registerConfigurationMigrations extension API (#14298)

Adds `positron.workspace.registerConfigurationMigrations` to the
Positron extension API, allowing extensions to declaratively migrate
configuration keys they previously contributed.

---------

Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: samclark2015

product.json

@@ -691,6 +691,7 @@
 			"languageModelSystem"
 		]
 	},
+	"trustedExtensionPublishers": ["posit", "rstudio"],
 	"trustedExtensionAuthAccess": {
 		"github": [],
 		"github-enterprise": [

src/positron-dts/positron.d.ts

@@ -3997,4 +3997,40 @@ declare module 'positron' {
 		 */
 		export function clearCellOutputs(notebookUri: string, cellIndices?: number[]): Thenable<void>;
 	}
+
+	/**
+	 * A specification for migrating one configuration key to another.
+	 * Used with {@link workspace.registerConfigurationMigrations}.
+	 */
+	export interface ConfigurationMigrationSpec {
+		/** The configuration key to migrate from. */
+		readonly key: string;
+		/** The configuration key to migrate to. */
+		readonly migrateTo: string;
+	}
+
+	export namespace workspace {
+
+		/**
+		 * Register configuration key migrations. Each migration copies a value from an old
+		 * configuration key to a new key and clears the old key. If the destination key
+		 * already has a user-set value at the same configuration target, the old key is
+		 * cleared without overwriting the new value.
+		 *
+		 * Ownership of the source keys is required and determined in order:
+		 * 1. The key is still registered and its `source` matches the calling extension.
+		 * 2. The key has no registered extension owner (e.g. removed from the manifest after
+		 *    renaming) and the key starts with `{extensionId}.` — namespace ownership.
+		 *
+		 * Ownership checks are bypassed entirely for extensions published by `posit`.
+		 *
+		 * If the old key is enforced by system policy but the new key is not, the migration
+		 * will log an error and notify the user; the admin should update the policy to use
+		 * the new key.
+		 *
+		 * @param migrations Array of migration specifications.
+		 * @returns A {@link vscode.Disposable} (unregistering is not supported; dispose is a no-op).
+		 */
+		export function registerConfigurationMigrations(migrations: ReadonlyArray<ConfigurationMigrationSpec>): vscode.Disposable;
+	}
 }

src/vs/workbench/api/browser/mainThreadConfiguration.ts

@@ -12,6 +12,13 @@ import { MainThreadConfigurationShape, MainContext, ExtHostContext, IConfigurati
 import { extHostNamedCustomer, IExtHostContext } from '../../services/extensions/common/extHostCustomers.js';
 import { ConfigurationTarget, IConfigurationService, IConfigurationOverrides } from '../../../platform/configuration/common/configuration.js';
 import { IEnvironmentService } from '../../../platform/environment/common/environment.js';
+// --- Start Positron ---
+import * as nls from '../../../nls.js';
+import { ILogService } from '../../../platform/log/common/log.js';
+import { INotificationService, Severity } from '../../../platform/notification/common/notification.js';
+import { IProductService } from '../../../platform/product/common/productService.js';
+import { Extensions as ConfigurationMigrationExtensions, IConfigurationMigrationRegistry, ConfigurationKeyValuePairs } from '../../common/configuration.js';
+// --- End Positron ---
 
 @extHostNamedCustomer(MainContext.MainThreadConfiguration)
 export class MainThreadConfiguration implements MainThreadConfigurationShape {
@@ -23,6 +30,11 @@ export class MainThreadConfiguration implements MainThreadConfigurationShape {
 		@IWorkspaceContextService private readonly _workspaceContextService: IWorkspaceContextService,
 		@IConfigurationService private readonly configurationService: IConfigurationService,
 		@IEnvironmentService private readonly _environmentService: IEnvironmentService,
+		// --- Start Positron ---
+		@ILogService private readonly _logService: ILogService,
+		@INotificationService private readonly _notificationService: INotificationService,
+		@IProductService private readonly _productService: IProductService,
+		// --- End Positron ---
 	) {
 		const proxy = extHostContext.getProxy(ExtHostContext.ExtHostConfiguration);
 
@@ -41,6 +53,72 @@ export class MainThreadConfiguration implements MainThreadConfigurationShape {
 		return configurationData;
 	}
 
+	// --- Start Positron ---
+	$registerConfigurationMigrations(extensionId: string, migrations: ReadonlyArray<{ readonly key: string; readonly migrateTo: string }>): void {
+		const configurationProperties = Registry.as<IConfigurationRegistry>(ConfigurationExtensions.Configuration).getConfigurationProperties();
+		const normalizedExtensionId = extensionId.toLowerCase();
+		const publisher = normalizedExtensionId.split('.')[0];
+		const isTrusted = (this._productService.trustedExtensionPublishers ?? []).includes(publisher);
+
+		const approved = migrations.filter(migration => {
+			const source = configurationProperties[migration.key]?.source;
+			const sourceId = (source && typeof source !== 'string')
+				? source.id.toLowerCase()
+				: undefined;
+			const isRegisteredOwner = sourceId === normalizedExtensionId;
+			// When the key has no extension owner (unregistered after a rename, or never attributed),
+			// accept ownership if the key falls within the extension's namespace.
+			const isNamespaceOwner = sourceId === undefined && migration.key.toLowerCase().startsWith(normalizedExtensionId + '.');
+			const isOwner = isRegisteredOwner || isNamespaceOwner;
+			if (!isOwner && !isTrusted) {
+				this._logService.warn(`Extension '${extensionId}' attempted to register a configuration migration for '${migration.key}' but does not own it.`);
+				return false;
+			}
+			return true;
+		});
+
+		const policyConflicts = approved.filter(migration => {
+			const oldPolicyValue = this.configurationService.inspect(migration.key)?.policyValue;
+			const newPolicyValue = this.configurationService.inspect(migration.migrateTo)?.policyValue;
+			return oldPolicyValue !== undefined && newPolicyValue === undefined;
+		});
+
+		for (const migration of policyConflicts) {
+			this._logService.error(
+				`Admin policy enforces '${migration.key}' but not '${migration.migrateTo}'. ` +
+				`Migration registered by '${extensionId}' may not behave correctly.`
+			);
+		}
+
+		if (policyConflicts.length > 0) {
+			const keyList = policyConflicts.map(m => `'${m.key}'`).join(', ');
+			this._notificationService.notify({
+				severity: Severity.Warning,
+				message: nls.localize(
+					'positron.configurationMigration.policyConflict',
+					"Some configuration migrations registered by '{0}' are blocked by system policy ({1}). Contact your administrator to update the policy.",
+					extensionId,
+					keyList,
+				),
+			});
+		}
+
+		if (approved.length > 0) {
+			Registry.as<IConfigurationMigrationRegistry>(ConfigurationMigrationExtensions.ConfigurationMigration)
+				.registerConfigurationMigrations(approved.map(migration => ({
+					key: migration.key,
+					migrateFn: (value: unknown, accessor: (key: string) => unknown): ConfigurationKeyValuePairs => {
+						const pairs: ConfigurationKeyValuePairs = [[migration.key, { value: undefined }]];
+						if (value !== undefined && accessor(migration.migrateTo) === undefined) {
+							pairs.push([migration.migrateTo, { value }]);
+						}
+						return pairs;
+					},
+				})));
+		}
+	}
+	// --- End Positron ---
+
 	public dispose(): void {
 		this._configurationListener.dispose();
 	}

src/vs/workbench/api/common/extHost.protocol.ts

@@ -247,6 +247,9 @@ export interface MainThreadSecretStateShape extends IDisposable {
 export interface MainThreadConfigurationShape extends IDisposable {
 	$updateConfigurationOption(target: ConfigurationTarget | null, key: string, value: unknown, overrides: IConfigurationOverrides | undefined, scopeToLanguage: boolean | undefined): Promise<void>;
 	$removeConfigurationOption(target: ConfigurationTarget | null, key: string, overrides: IConfigurationOverrides | undefined, scopeToLanguage: boolean | undefined): Promise<void>;
+	// --- Start Positron ---
+	$registerConfigurationMigrations(extensionId: string, migrations: ReadonlyArray<{ readonly key: string; readonly migrateTo: string }>): void;
+	// --- End Positron ---
 }
 
 export interface MainThreadDiagnosticsShape extends IDisposable {

src/vs/workbench/api/common/extHostConfiguration.ts

@@ -134,6 +134,12 @@ export class ExtHostConfiguration implements ExtHostConfigurationShape {
 	$acceptConfigurationChanged(data: IConfigurationInitData, change: IConfigurationChange): void {
 		this.getConfigProvider().then(provider => provider.$acceptConfigurationChanged(data, change));
 	}
+
+	// --- Start Positron ---
+	registerConfigurationMigrations(extension: IExtensionDescription, migrations: ReadonlyArray<{ readonly key: string; readonly migrateTo: string }>): void {
+		this._proxy.$registerConfigurationMigrations(extension.identifier.value, migrations);
+	}
+	// --- End Positron ---
 }
 
 export class ExtHostConfigProvider {

src/vs/workbench/api/common/positron/extHost.positron.api.impl.ts

@@ -12,7 +12,7 @@ import { ILogService } from '../../../../platform/log/common/log.js';
 import { ServicesAccessor } from '../../../../platform/instantiation/common/instantiation.js';
 import { IExtensionRegistries } from '../extHost.api.impl.js';
 import { IExtensionDescription } from '../../../../platform/extensions/common/extensions.js';
-import { ExtHostConfigProvider } from '../extHostConfiguration.js';
+import { ExtHostConfigProvider, IExtHostConfiguration } from '../extHostConfiguration.js';
 import { ExtHostPositronContext } from './extHost.positron.protocol.js';
 import * as extHostTypes from './extHostTypes.positron.js';
 import { NotebookCellType } from '../../../common/positron/notebookAssistant.js';
@@ -64,6 +64,7 @@ export function createPositronApiFactoryAndRegisterActors(accessor: ServicesAcce
 	const extHostWorkspace = accessor.get(IExtHostWorkspace);
 	const extHostCommands = accessor.get(IExtHostCommands);
 	const extHostLogService = accessor.get(ILogService);
+	const extHostConfiguration = accessor.get(IExtHostConfiguration);
 
 	// Retrieve the raw `ExtHostWebViews` object from the rpcProtocol; this
 	// object is needed to create webviews, and was previously created in
@@ -618,6 +619,13 @@ export function createPositronApiFactoryAndRegisterActors(accessor: ServicesAcce
 			}
 		};
 
+		const workspace: typeof positron.workspace = {
+			registerConfigurationMigrations(migrations: ReadonlyArray<positron.ConfigurationMigrationSpec>): vscode.Disposable {
+				extHostConfiguration.registerConfigurationMigrations(extension, migrations);
+				return { dispose: () => { } };
+			},
+		};
+
 		// --- End Positron ---
 
 		return {
@@ -635,6 +643,7 @@ export function createPositronApiFactoryAndRegisterActors(accessor: ServicesAcce
 			dataExplorer,
 			ai,
 			notebooks,
+			workspace,
 			CodeAttributionSource: extHostTypes.CodeAttributionSource,
 			PositronLanguageModelType: extHostTypes.PositronLanguageModelType,
 			PositronChatAgentLocation: extHostTypes.PositronChatAgentLocation,

src/vs/workbench/api/test/browser/mainThreadConfiguration.test.ts

@@ -16,6 +16,12 @@ import { IConfigurationService, ConfigurationTarget } from '../../../../platform
 import { WorkspaceService } from '../../../services/configuration/browser/configurationService.js';
 import { IEnvironmentService } from '../../../../platform/environment/common/environment.js';
 import { ensureNoDisposablesAreLeakedInTestSuite } from '../../../../base/test/common/utils.js';
+// --- Start Positron ---
+import { ILogService, NullLogService } from '../../../../platform/log/common/log.js';
+import { INotificationService, NoOpNotification } from '../../../../platform/notification/common/notification.js';
+import { IProductService } from '../../../../platform/product/common/productService.js';
+import { Extensions as ConfigurationMigrationExtensions, IConfigurationMigrationRegistry } from '../../../common/configuration.js';
+// --- End Positron ---
 
 suite('MainThreadConfiguration', function () {
 
@@ -60,6 +66,10 @@ suite('MainThreadConfiguration', function () {
 		instantiationService.stub(IEnvironmentService, {
 			isBuilt: false
 		});
+		// --- Start Positron ---
+		instantiationService.stub(ILogService, new NullLogService());
+		instantiationService.stub(IProductService, { trustedExtensionPublishers: ['posit', 'rstudio'] });
+		// --- End Positron ---
 	});
 
 	teardown(() => {
@@ -236,4 +246,104 @@ suite('MainThreadConfiguration', function () {
 
 		assert.strictEqual(ConfigurationTarget.WORKSPACE_FOLDER, target.args[0][3]);
 	});
+
+	// --- Start Positron ---
+	suite('registerConfigurationMigrations', function () {
+
+		const OWNED_KEY = 'extHostConfigMigration.oldKey';
+		const OWNER_EXT = 'test.owner';
+
+		suiteSetup(() => {
+			Registry.as<IConfigurationRegistry>(Extensions.Configuration).registerConfiguration({
+				id: 'extHostConfigMigration',
+				type: 'object',
+				extensionInfo: { id: OWNER_EXT },
+				properties: {
+					[OWNED_KEY]: { type: 'boolean', description: 'test key for migration tests' }
+				}
+			});
+		});
+
+		let migrationRegistry: IConfigurationMigrationRegistry;
+		let registerSpy: sinon.SinonSpy;
+		let warnSpy: sinon.SinonSpy;
+
+		setup(() => {
+			migrationRegistry = Registry.as<IConfigurationMigrationRegistry>(ConfigurationMigrationExtensions.ConfigurationMigration);
+			registerSpy = sinon.spy(migrationRegistry, 'registerConfigurationMigrations');
+			const logService = new NullLogService();
+			warnSpy = sinon.spy(logService, 'warn');
+			instantiationService.stub(ILogService, logService);
+			instantiationService.stub(INotificationService, { notify: () => new NoOpNotification() });
+			instantiationService.stub(IWorkspaceContextService, <IWorkspaceContextService>{ getWorkbenchState: () => WorkbenchState.FOLDER });
+		});
+
+		teardown(() => {
+			registerSpy.restore();
+		});
+
+		test('owned key is accepted and migrateFn maps value correctly', function () {
+			const testObject = instantiationService.createInstance(MainThreadConfiguration, SingleProxyRPCProtocol(proxy));
+
+			testObject.$registerConfigurationMigrations(OWNER_EXT, [{ key: OWNED_KEY, migrateTo: 'extHostConfigMigration.newKey' }]);
+
+			assert.ok(registerSpy.calledOnce, 'registerConfigurationMigrations should be called once');
+			const [migrations] = registerSpy.args[0] as [Array<{ key: string; migrateFn: (v: unknown, accessor: (k: string) => unknown) => unknown }>];
+			assert.strictEqual(migrations.length, 1);
+			assert.strictEqual(migrations[0].key, OWNED_KEY);
+			// accessor returns undefined → new key not yet set → migration copies value
+			const result = migrations[0].migrateFn('testValue', () => undefined);
+			assert.deepStrictEqual(result, [
+				[OWNED_KEY, { value: undefined }],
+				['extHostConfigMigration.newKey', { value: 'testValue' }],
+			]);
+		});
+
+		test('unowned key is rejected and a warning is logged', function () {
+			const testObject = instantiationService.createInstance(MainThreadConfiguration, SingleProxyRPCProtocol(proxy));
+
+			testObject.$registerConfigurationMigrations('other.extension', [{ key: OWNED_KEY, migrateTo: 'extHostConfigMigration.newKey' }]);
+
+			assert.ok(warnSpy.calledOnce, 'warn should be called for unowned key');
+			assert.ok(registerSpy.notCalled, 'registerConfigurationMigrations should not be called');
+		});
+
+		test('trusted publisher bypasses ownership check', function () {
+			const testObject = instantiationService.createInstance(MainThreadConfiguration, SingleProxyRPCProtocol(proxy));
+
+			testObject.$registerConfigurationMigrations('posit.extension', [{ key: OWNED_KEY, migrateTo: 'extHostConfigMigration.newKey' }]);
+
+			assert.ok(registerSpy.calledOnce, 'posit publisher should be able to migrate unowned key');
+			assert.ok(warnSpy.notCalled, 'no warning should be logged for posit publisher');
+
+			registerSpy.resetHistory();
+			warnSpy.resetHistory();
+
+			testObject.$registerConfigurationMigrations('rstudio.rstudio-workbench', [{ key: OWNED_KEY, migrateTo: 'extHostConfigMigration.newKey' }]);
+
+			assert.ok(registerSpy.calledOnce, 'rstudio publisher should be able to migrate unowned key');
+			assert.ok(warnSpy.notCalled, 'no warning should be logged for rstudio publisher');
+		});
+
+		test('unregistered key is accepted when it matches extension namespace', function () {
+			const testObject = instantiationService.createInstance(MainThreadConfiguration, SingleProxyRPCProtocol(proxy));
+			const droppedKey = `${OWNER_EXT}.droppedKey`; // never registered; simulates rename-and-remove
+
+			testObject.$registerConfigurationMigrations(OWNER_EXT, [{ key: droppedKey, migrateTo: 'extHostConfigMigration.newKey' }]);
+
+			assert.ok(registerSpy.calledOnce, 'migration for unregistered key in extension namespace should be accepted');
+			assert.ok(warnSpy.notCalled, 'no warning should be logged for namespace-owned key');
+		});
+
+		test('unregistered key outside extension namespace is rejected', function () {
+			const testObject = instantiationService.createInstance(MainThreadConfiguration, SingleProxyRPCProtocol(proxy));
+			const foreignKey = 'other.publisher.droppedKey'; // unregistered and wrong namespace
+
+			testObject.$registerConfigurationMigrations(OWNER_EXT, [{ key: foreignKey, migrateTo: 'extHostConfigMigration.newKey' }]);
+
+			assert.ok(warnSpy.calledOnce, 'warn should be called for unregistered key outside extension namespace');
+			assert.ok(registerSpy.notCalled, 'migration should not be registered');
+		});
+	});
+	// --- End Positron ---
 });

src/vs/workbench/common/configuration.ts

@@ -77,6 +77,10 @@ class ConfigurationMigrationRegistry implements IConfigurationMigrationRegistry
 
 	registerConfigurationMigrations(configurationMigrations: ConfigurationMigration[]): void {
 		this.migrations.push(...configurationMigrations);
+		// --- Start Positron ---
+		// Fire the event so ConfigurationMigrationWorkbenchContribution processes dynamically registered migrations.
+		this._onDidRegisterConfigurationMigrations.fire(configurationMigrations);
+		// --- End Positron ---
 	}
 
 }

src/vs/workbench/common/test/configuration.vitest.ts

@@ -0,0 +1,32 @@
+/*---------------------------------------------------------------------------------------------
+ *  Copyright (C) 2026 Posit Software, PBC. All rights reserved.
+ *  Licensed under the Elastic License 2.0. See LICENSE.txt for license information.
+ *--------------------------------------------------------------------------------------------*/
+
+/// <reference types="vitest/globals" />
+
+import { Registry } from '../../../platform/registry/common/platform.js';
+import { Extensions, IConfigurationMigrationRegistry, ConfigurationMigration } from '../configuration.js';
+import { Event } from '../../../base/common/event.js';
+
+describe('ConfigurationMigrationRegistry', () => {
+
+	it('fires onDidRegisterConfigurationMigration when migrations are registered', () => {
+		const registry = Registry.as<IConfigurationMigrationRegistry & { onDidRegisterConfigurationMigration: Event<ConfigurationMigration[]> }>(Extensions.ConfigurationMigration);
+
+		const fired: ConfigurationMigration[][] = [];
+		const disposable = registry.onDidRegisterConfigurationMigration(m => fired.push(m));
+
+		const migration: ConfigurationMigration = {
+			key: 'test.eventFiringKey',
+			migrateFn: (value: unknown) => [['test.eventFiringKeyNew', { value }]],
+		};
+		registry.registerConfigurationMigrations([migration]);
+
+		disposable.dispose();
+
+		expect(fired).toHaveLength(1);
+		expect(fired[0]).toHaveLength(1);
+		expect(fired[0][0].key).toBe('test.eventFiringKey');
+	});
+});