API: Advertise EnvironmentManager and PackageManager capabilities (#1874)

Contributes to #1837.

## Summary

Adds manager-agnostic feature detection for environment and package
managers, with flat capability keys exposed through
`EnvironmentCapability` and `PackageCapability`.

- Managers may advertise contextual, read-only checks returning
`Support`: supported, or unsupported with a reason. Support is advisory;
unexpected probe failures reject rather than being treated as
unsupported.
- Capability maps are optional for legacy compatibility. Omitted maps
use the new method-presence inference helpers and return `isLegacy:
true`. Supplied maps must advertise every catalog key; missing keys
return unsupported without legacy inference.
- Adds public `getEnvironmentManagerCapability` and
`getPackageManagerCapability` queries. Queries use currently registered
providers without activation, registration waits, or prompts. Package
queries honor project-bound routing; unregistered explicit projects
return unavailable rather than using a containing project's provider.
- Built-in managers advertise extension-supported behavior, including
inline-script creation requirements, Poetry project binding, pip
version-lookup support, and the Python 2 restriction on pip
installation, uninstallation, and upgrades.
- Adds capability-query telemetry with the routed manager, tool version,
outcome, and legacy flag. Version collection runs asynchronously with a
one-second timeout and cannot delay support results or probe errors.
- Bumps `@vscode/python-environments` to **1.7.0** and updates public
exports, package source copying, API-change checks, and documentation.

## Validation

- Lint and TypeScript checks passed.
- Extension and API package builds passed; modern and legacy API
consumer type-checks passed.
- **2,883 unit tests passed**, with 7 pending.
- **2 capability integration tests passed**, including production
nested-project routing coverage.

---------

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Copilot-Session: 408a66e2-1fd6-432d-9ce9-fa2cff9313ea

Author: 3 people

.github/workflows/pr-file-check.yml

@@ -49,6 +49,8 @@ jobs:
             src/api.ts
             src/types.ts
             src/publicErrors.ts
+            src/capabilities.ts
+            src/legacyCapabilities.ts
           file-pattern: 'api/package.json'
           skip-label: 'skip api version'
           failure-message: 'The public API (${prereq-pattern}) was changed without bumping the package version in ${file-pattern} (the ${skip-label} label can be used to pass this check)'
@@ -60,6 +62,8 @@ jobs:
             src/api.ts
             src/types.ts
             src/publicErrors.ts
+            src/capabilities.ts
+            src/legacyCapabilities.ts
           file-pattern: 'api/CHANGELOG.md'
           skip-label: 'skip api changelog'
           failure-message: 'The public API (${prereq-pattern}) was changed without a changelog entry in ${file-pattern} (the ${skip-label} label can be used to pass this check)'
@@ -71,6 +75,8 @@ jobs:
             src/api.ts
             src/types.ts
             src/publicErrors.ts
+            src/capabilities.ts
+            src/legacyCapabilities.ts
           file-pattern: 'docs/README.md'
           skip-label: 'skip api docs'
           failure-message: 'The public API (${prereq-pattern}) was changed without updating ${file-pattern} (the ${skip-label} label can be used to pass this check)'

api/.gitignore

@@ -1,7 +1,3 @@
-# Copied from ../src/api.ts, ../src/types.ts, ../src/publicErrors.ts by the publish pipeline
-# (build/azure-pipeline.npm.yml). These are the published package sources; they are produced
-# at publish time and intentionally NOT committed. src/api.ts, src/types.ts, and
-# src/publicErrors.ts are the single sources of truth.
-src/main.ts
-src/types.ts
-src/publicErrors.ts
+# Generated package sources copied from ../src by scripts/copy-sources.cjs.
+# The original files under ../src are the single sources of truth.
+/src/

api/CHANGELOG.md

@@ -5,6 +5,21 @@ All notable changes to the `@vscode/python-environments` API package are documen
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.7.0]
+
+### Added
+
+- Optional `capabilities` maps for environment and package managers, with typed keys and contextual checks. Omitted maps use legacy method inference; when present, the map must advertise every catalog key explicitly, and missing keys resolve unsupported.
+- Raw-provider capability resolvers and routed extension API queries that report support without invoking manager operations or prompting.
+- Capability catalogs for six environment and six package features, with flat operation names. Listing includes refresh, and package installation, uninstallation, and upgrades are advertised individually rather than through a management umbrella.
+- Exported `EnvironmentCapability` and `PackageCapability` constant objects for named access to capability keys, with derived string-literal unions.
+- `getLegacyPackageManagerCapability` and `getLegacyEnvironmentManagerCapability` helpers that infer support from method presence without invoking operations. Resolvers use them automatically when a provider omits its capability map.
+- Optional `Support.isLegacy` metadata, set to true by legacy inference helpers and included in public capability-query telemetry.
+
+### Notes
+
+- Capability prerequisite checks have no cycle protection; providers must keep delegation chains acyclic.
+
 ## [1.6.0]
 
 ### Added

api/README.md

@@ -35,6 +35,30 @@ export async function activate() {
 }
 ```
 
+## Manager capabilities
+
+Capabilities report general manager support without invoking an operation:
+
+```typescript
+import { PackageCapability, PythonEnvironments } from '@vscode/python-environments';
+
+const api = await PythonEnvironments.api();
+const environment = await api.getEnvironment(undefined);
+if (environment) {
+    const support = await api.getPackageManagerCapability(environment, PackageCapability.ListDirect);
+    if (support.supported) {
+        // Best-effort direct/transitive package classification is available.
+    }
+}
+```
+
+Manager advertisements are optional for legacy compatibility. Missing maps use
+method-presence inference and return `isLegacy: true`; missing keys in a supplied
+map report unsupported. Support is advisory, not a guarantee that an operation succeeds.
+
+See the [capability guide](https://github.com/microsoft/vscode-python-environments/blob/main/docs/README.md#manager-capabilities)
+for the full catalog and provider authoring.
+
 ## Full API reference
 
 📘 **[Python Environments API reference](https://github.com/microsoft/vscode-python-environments/blob/main/docs/README.md)**
@@ -51,4 +75,3 @@ extensibility - with field tables, parameter tables, return types, and examples.
 - [Extensibility](https://github.com/microsoft/vscode-python-environments/blob/main/docs/README.md#extensibility) - register your own environment manager, package manager, or project creator
 
 See [`CHANGELOG.md`](https://github.com/microsoft/vscode-python-environments/blob/main/api/CHANGELOG.md) for API changes between versions.
-

api/package-lock.json

@@ -1,7 +1,7 @@
 {
     "name": "@vscode/python-environments",
     "description": "An API facade for the Python Environments extension in VS Code",
-    "version": "1.6.0",
+    "version": "1.7.0",
     "author": {
         "name": "Microsoft Corporation"
     },

api/package.json

@@ -17,6 +17,8 @@ const sources = [
     { from: path.join(repoRoot, 'src', 'api.ts'), to: path.join(srcDir, 'main.ts') },
     { from: path.join(repoRoot, 'src', 'types.ts'), to: path.join(srcDir, 'types.ts') },
     { from: path.join(repoRoot, 'src', 'publicErrors.ts'), to: path.join(srcDir, 'publicErrors.ts') },
+    { from: path.join(repoRoot, 'src', 'capabilities.ts'), to: path.join(srcDir, 'capabilities.ts') },
+    { from: path.join(repoRoot, 'src', 'legacyCapabilities.ts'), to: path.join(srcDir, 'legacyCapabilities.ts') },
 ];
 
 fs.mkdirSync(srcDir, { recursive: true });

api/scripts/copy-sources.cjs

@@ -94,6 +94,7 @@ try {
             "};",
             'exports.__runtimeApi = runtimeApi;',
             'exports.extensions = { getExtension: () => extension };',
+            'exports.l10n = { t: (message) => message };',
         ].join('\n'),
     );
     const installedPackageJson = JSON.parse(fs.readFileSync(path.join(installedPackageRoot, 'package.json'), 'utf8'));

api/scripts/test-package.cjs

@@ -1,59 +1,148 @@
 import type {
+    Capabilities,
+    CapabilityContext,
+    EnvironmentManager,
+    EnvironmentManagerCapability,
     PackageManager,
+    PackageManagerCapability,
     Pep440Version,
     PythonEnvironment,
     PythonEnvironmentApi,
     PythonPackageGetterApi,
+    Support,
 } from '@vscode/python-environments';
 import {
+    EnvironmentCapability,
+    getLegacyEnvironmentManagerCapability,
+    getLegacyPackageManagerCapability,
     isPackageVersionLookupNotSupportedError,
+    PackageCapability,
     PackageVersionLookupNotSupportedError,
     PythonEnvironments,
+    resolveEnvironmentManagerCapability,
+    resolvePackageManagerCapability,
+    supportedCapability,
 } from '@vscode/python-environments';
 
 type Equal<Left, Right> =
     (<Value>() => Value extends Left ? 1 : 2) extends <Value>() => Value extends Right ? 1 : 2 ? true : false;
 
+// Compile-only fixture shared by modern and legacy consumers; not executed.
+declare const api: PythonEnvironmentApi;
+declare const environment: PythonEnvironment;
+PythonEnvironments.api() satisfies Promise<PythonEnvironmentApi>;
+
+// Package version lookup contracts.
 type AvailableVersionsReturn = ReturnType<PythonPackageGetterApi['getPackageAvailableVersions']>;
 type RefreshReturn = ReturnType<PackageManager['refresh']>;
 
-const availableVersionsReturnIsExact: Equal<AvailableVersionsReturn, Promise<Pep440Version[] | undefined>> = true;
-const refreshReturnIsExact: Equal<RefreshReturn, Promise<void>> = true;
+true satisfies Equal<AvailableVersionsReturn, Promise<Pep440Version[] | undefined>>;
+true satisfies Equal<RefreshReturn, Promise<void>>;
 
-declare const api: PythonPackageGetterApi;
-declare const environment: PythonEnvironment;
-const legacyAvailableVersions: Promise<Pep440Version[] | undefined> = api.getPackageAvailableVersions(
-    environment,
-    'example',
-);
-const explicitLegacyAvailableVersions: Promise<Pep440Version[] | undefined> = api.getPackageAvailableVersions(
-    environment,
-    'example',
-    { errorMode: 'legacy' },
-);
-const throwingAvailableVersions: Promise<Pep440Version[]> = api.getPackageAvailableVersions(environment, 'example', {
-    errorMode: 'throw',
-});
-const runtimeApi: Promise<PythonEnvironmentApi> = PythonEnvironments.api();
-
-// The unsupported-capability error is part of the public contract: it is constructible, extends
-// Error, and exposes a stable string-literal `code` discriminator.
+api.getPackageAvailableVersions(environment, 'example') satisfies Promise<Pep440Version[] | undefined>;
+api.getPackageAvailableVersions(environment, 'example', {
+    errorMode: 'legacy',
+}) satisfies Promise<Pep440Version[] | undefined>;
+api.getPackageAvailableVersions(environment, 'example', { errorMode: 'throw' }) satisfies Promise<Pep440Version[]>;
+
+// Public error construction, discriminator, and narrowing.
 const lookupError = new PackageVersionLookupNotSupportedError('unsupported');
-const lookupErrorIsError: Error = lookupError;
-const lookupErrorCodeIsExact: Equal<typeof lookupError.code, 'PackageVersionLookupNotSupported'> = true;
+lookupError satisfies Error;
+true satisfies Equal<typeof lookupError.code, 'PackageVersionLookupNotSupported'>;
 
-// The type guard narrows unknown values via the stable discriminator (bundle-boundary safe).
 declare const maybeError: unknown;
-const guardNarrows: boolean = isPackageVersionLookupNotSupportedError(maybeError)
-    ? maybeError.code === 'PackageVersionLookupNotSupported'
-    : false;
-
-void availableVersionsReturnIsExact;
-void refreshReturnIsExact;
-void legacyAvailableVersions;
-void explicitLegacyAvailableVersions;
-void throwingAvailableVersions;
-void runtimeApi;
-void lookupErrorIsError;
-void lookupErrorCodeIsExact;
-void guardNarrows;
+if (isPackageVersionLookupNotSupportedError(maybeError)) {
+    maybeError.code satisfies 'PackageVersionLookupNotSupported';
+}
+
+// Legacy providers may omit advertisements; advertised maps must include every key without defaults.
+true satisfies Equal<typeof PackageCapability.ListDirect, 'packages.list.direct'>;
+true satisfies Equal<typeof PackageCapability.FetchAvailableVersions, 'packages.fetchversions'>;
+const fullPackageCapabilities: Capabilities<PackageManagerCapability> = {
+    [PackageCapability.List]: supportedCapability,
+    [PackageCapability.Install]: supportedCapability,
+    [PackageCapability.Uninstall]: supportedCapability,
+    [PackageCapability.Upgrade]: supportedCapability,
+    [PackageCapability.ListDirect]: supportedCapability,
+    [PackageCapability.FetchAvailableVersions]: supportedCapability,
+};
+const fullEnvironmentCapabilities: Capabilities<EnvironmentManagerCapability> = {
+    [EnvironmentCapability.List]: supportedCapability,
+    [EnvironmentCapability.Resolve]: supportedCapability,
+    [EnvironmentCapability.GetSelected]: supportedCapability,
+    [EnvironmentCapability.SetSelected]: supportedCapability,
+    [EnvironmentCapability.Create]: supportedCapability,
+    [EnvironmentCapability.Remove]: supportedCapability,
+};
+
+const legacyPackageManager: PackageManager = {
+    name: 'legacy',
+    manage: async () => {},
+    refresh: async () => {},
+    getPackages: async () => [],
+};
+const legacyEnvironmentManager: EnvironmentManager = {
+    name: 'legacy',
+    preferredPackageManagerId: 'example:legacy',
+    refresh: async () => {},
+    getEnvironments: async () => [],
+    get: async () => undefined,
+    set: async () => {},
+    resolve: async () => undefined,
+};
+
+getLegacyPackageManagerCapability(legacyPackageManager, PackageCapability.Install) satisfies Promise<Support>;
+getLegacyEnvironmentManagerCapability(legacyEnvironmentManager, EnvironmentCapability.Create) satisfies Promise<Support>;
+
+// Capability authoring and raw-provider resolution.
+const advertised: Capabilities<PackageManagerCapability> = {
+    ...fullPackageCapabilities,
+    [PackageCapability.Upgrade]: (context: CapabilityContext) =>
+        resolvePackageManagerCapability(legacyPackageManager, PackageCapability.Install, context),
+    [PackageCapability.ListDirect]: async (_context) => ({ supported: false, reason: 'Unavailable' }),
+};
+const managerWithCapabilities: PackageManager = { ...legacyPackageManager, capabilities: advertised };
+resolvePackageManagerCapability(managerWithCapabilities, PackageCapability.ListDirect, { environment }) satisfies Promise<Support>;
+resolveEnvironmentManagerCapability(legacyEnvironmentManager, EnvironmentCapability.Create, {
+    scope: 'global',
+}) satisfies Promise<Support>;
+
+// Public queries and support-result narrowing.
+api.getPackageManagerCapability(environment, PackageCapability.List) satisfies Promise<Support>;
+api.getEnvironmentManagerCapability('example:legacy', EnvironmentCapability.List, { scope: 'all' }) satisfies Promise<Support>;
+declare const support: Support;
+support.isLegacy satisfies boolean | undefined;
+if (!support.supported) {
+    support.reason satisfies string;
+}
+
+// Invalid capability keys, advertisements, and context must remain compile errors.
+// @ts-expect-error Legacy environment inference requires an environment capability.
+getLegacyEnvironmentManagerCapability(legacyEnvironmentManager, PackageCapability.List);
+// @ts-expect-error Legacy package inference requires a package capability.
+getLegacyPackageManagerCapability(legacyPackageManager, EnvironmentCapability.List);
+// @ts-expect-error Package keys do not belong to the environment capability domain.
+PackageCapability.List satisfies EnvironmentManagerCapability;
+// @ts-expect-error Environment keys do not belong to the package capability domain.
+EnvironmentCapability.List satisfies PackageManagerCapability;
+// @ts-expect-error Advertisements must be asynchronous functions, not static Support values.
+({ [PackageCapability.List]: { supported: true } } satisfies Capabilities<PackageManagerCapability>);
+// @ts-expect-error Advertisements cannot introduce arbitrary keys.
+({ 'packages.unknown': async () => ({ supported: true }) } satisfies Capabilities<PackageManagerCapability>);
+// @ts-expect-error Operation options are not capability query context.
+({ createOptions: { quickCreate: true } } satisfies CapabilityContext);
+declare const arbitraryKey: string;
+// @ts-expect-error A general string is not a declared environment capability.
+resolveEnvironmentManagerCapability(legacyEnvironmentManager, arbitraryKey);
+// @ts-expect-error A general string is not a declared package capability.
+resolvePackageManagerCapability(legacyPackageManager, arbitraryKey);
+// @ts-expect-error Public environment queries require a catalog key.
+api.getEnvironmentManagerCapability('example:legacy', arbitraryKey);
+// @ts-expect-error Public package queries require a catalog key.
+api.getPackageManagerCapability(environment, arbitraryKey);
+// @ts-expect-error Capability dictionaries have no arbitrary string index signature.
+fullPackageCapabilities[arbitraryKey];
+// @ts-expect-error Capability dictionaries have no arbitrary string index signature.
+fullEnvironmentCapabilities[arbitraryKey];
+// @ts-expect-error Capability dictionaries must advertise every catalog key; partial maps are rejected.
+({ [PackageCapability.List]: async () => ({ supported: true }) } satisfies Capabilities<PackageManagerCapability>);

api/test/consumer.ts

@@ -86,7 +86,7 @@ extends:
 
               - script: npm run copy:sources
                 workingDirectory: $(Build.SourcesDirectory)/api
-                displayName: Copy src/api.ts, src/types.ts, src/publicErrors.ts to API package sources
+                displayName: Copy API facade, types, errors, and capabilities to API package sources
 
               - script: npm run compile
                 workingDirectory: $(Build.SourcesDirectory)/api