@vscode/python-environments 1.0.0 → 1.4.0

package/CHANGELOG.md

@@ -0,0 +1,49 @@
+# Changelog
+
+All notable changes to the `@vscode/python-environments` API package are documented in this file.
+
+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.4.0]
+
+### Changed
+
+- Reorganized the package source into separate API facade, public contract, and public error modules without changing the root package exports.
+
+## [1.3.0]
+
+### Added
+
+- Added `PackageVersionLookupNotSupportedError`, thrown when a package manager cannot list a package's available versions (an unsupported capability, as distinct from an operational failure). The error exposes a stable `code` (`'PackageVersionLookupNotSupported'`) discriminator.
+- Added the `isPackageVersionLookupNotSupportedError(error): error is PackageVersionLookupNotSupportedError` type guard. It recognizes the error via its stable `code`, so it works even when the error crosses an extension bundle boundary and `instanceof` would fail.
+- Added an optional `errorMode` to `PythonPackageGetterApi.getPackageAvailableVersions`. The default `legacy` mode preserves the existing `undefined` result for unsupported lookups and operational failures. The opt-in `throw` mode rejects with `PackageVersionLookupNotSupportedError` for unsupported capabilities and propagates operational failures unchanged.
+
+### Changed
+
+- Documented that `PackageManager.getPackageAvailableVersions` implementations should throw `PackageVersionLookupNotSupportedError` when version lookup is unsupported and let operational failures propagate. Resolving to `undefined` continues to be treated by callers as an unsupported capability.
+
+## [1.2.0]
+
+### Added
+
+- Added `PackageManagementInteractionOptions` with an optional `runHeadless?: boolean` property, mixed into `PackageManagementOptions`. When `true`, package management operations run without any user prompts or interaction — steps that would normally require input, such as selecting packages to install when none are specified, are skipped instead of prompting — for automated or headless scenarios such as integration tests.
+- Added `RemoveEnvironmentOptions` with an optional `runHeadless?: boolean` property to remove environments without a confirmation prompt in automated or headless scenarios.
+
+## [1.1.0]
+
+### Added
+
+- Re-exported the `Pep440Version` type from `@renovatebot/pep440` for use with the new package version APIs.
+- Added the optional `PackageInfo.isTransitive?: boolean` property to indicate whether a package is a transitive dependency.
+- Added `GetPackagesOptions` with an optional `skipCache?: boolean` property. When `true`, package managers bypass cached data and query the underlying package management tool.
+- Added optional `PackageManager.getPackageWatchTargets?(environment: PythonEnvironment): RelativePattern[]` to return manager-specific filesystem patterns to monitor for package installation and removal changes, in addition to the default site-packages metadata locations.
+- Added optional `PackageManager.getDirectPackageNames?(environment: PythonEnvironment): Promise<Set<string> | undefined>` to return a best-effort set of direct, non-transitive package names when supported by the package manager.
+- Added optional `PackageManager.getVersion?(environment: PythonEnvironment): Promise<Pep440Version | undefined>` to return the version of the underlying package management tool, such as pip, uv, or conda.
+- Added optional `PackageManager.getPackageAvailableVersions?(environment: PythonEnvironment, packageName: string): Promise<Pep440Version[] | undefined>` to return the available versions of a package in newest-first order when supported.
+- Added optional `PackageManager.formatInstallSpec?(packageName: string, version: string): string` to format a versioned install specification using manager-specific syntax, such as `name==version` for pip or `name=version` for conda.
+- Added `PythonPackageGetterApi.getPackageAvailableVersions(environment: PythonEnvironment, packageName: string): Promise<Pep440Version[] | undefined>` so API consumers can query a package's available versions in newest-first order. Resolves to `undefined` when the environment's package manager does not support version listing.
+
+### Changed
+
+- Added the optional `options?: GetPackagesOptions` parameter to `PackageManager.getPackages(environment, options?)` and `PythonPackageGetterApi.getPackages(environment, options?)`. Consumers can set `options.skipCache` to request fresh package data.

package/README.md

@@ -35,3 +35,20 @@ export async function activate() {
 }
 ```
 
+## Full API reference
+
+📘 **[Python Environments API reference](https://github.com/microsoft/vscode-python-environments/blob/main/docs/README.md)**
+
+The complete manual documents every method and data type, organized by domain -
+environments, packages, projects, execution, environment variables, and
+extensibility - with field tables, parameter tables, return types, and examples.
+
+- [Environments](https://github.com/microsoft/vscode-python-environments/blob/main/docs/README.md#environments) - discover, resolve, select, create, and remove interpreters
+- [Packages](https://github.com/microsoft/vscode-python-environments/blob/main/docs/README.md#packages) - list, install, uninstall, and look up versions
+- [Projects](https://github.com/microsoft/vscode-python-environments/blob/main/docs/README.md#projects) - the folders the extension tracks
+- [Execution](https://github.com/microsoft/vscode-python-environments/blob/main/docs/README.md#execution) - run Python in terminals, tasks, and background processes
+- [Environment variables](https://github.com/microsoft/vscode-python-environments/blob/main/docs/README.md#environment-variables) - resolved variables for a scope
+- [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.
+

package/out/cjs/main.cjs

@@ -0,0 +1,52 @@
+"use strict";
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PythonEnvironments = exports.EXTENSION_ID = void 0;
+const vscode_1 = require("vscode");
+/*
+ * Do not introduce any breaking changes to this API.
+ * This is the public API for other extensions to interact with the Python Environments extension.
+ *
+ * This module is a small public runtime/package facade: it re-exports all public type contracts
+ * from `./types` and the concrete error/guard from `./publicErrors`, and hosts the runtime surface
+ * (`EXTENSION_ID` and `PythonEnvironments.api()`).
+ */
+__exportStar(require("./types.js"), exports);
+__exportStar(require("./publicErrors.js"), exports);
+exports.EXTENSION_ID = 'ms-python.vscode-python-envs';
+var PythonEnvironments;
+(function (PythonEnvironments) {
+    /**
+     * Returns the API exposed by the Python Environments extension in VS Code.
+     */
+    async function api() {
+        const extension = vscode_1.extensions.getExtension(exports.EXTENSION_ID);
+        if (extension === undefined) {
+            throw new Error(`Python Environments extension (${exports.EXTENSION_ID}) is not installed or is disabled`);
+        }
+        if (!extension.isActive) {
+            await extension.activate();
+        }
+        const api = extension.exports;
+        if (!api) {
+            throw new Error(`Python Environments extension (${exports.EXTENSION_ID}) did not expose its API. Ensure "python.useEnvironmentsExtension" is enabled and reload the window.`);
+        }
+        return api;
+    }
+    PythonEnvironments.api = api;
+})(PythonEnvironments || (exports.PythonEnvironments = PythonEnvironments = {}));

package/out/cjs/publicErrors.js

@@ -0,0 +1,55 @@
+"use strict";
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PackageVersionLookupNotSupportedError = void 0;
+exports.isPackageVersionLookupNotSupportedError = isPackageVersionLookupNotSupportedError;
+/*
+ * Concrete, public runtime error type(s) for the Python Environments API.
+ * Kept separate from `./types.ts` (pure contracts) and re-exported from `./api.ts` to keep
+ * that facade small.
+ */
+/**
+ * Error thrown when a package manager cannot list available package versions.
+ *
+ * This distinguishes an *unsupported capability* from an *operational failure* (such as a
+ * failed command, a network error, or malformed/unparseable output). Consumers of
+ * {@link PythonPackageGetterApi.getPackageAvailableVersions} should treat this specific error
+ * as a signal to fall back to manual version entry, while letting any other error propagate.
+ *
+ * The {@link code} property carries a stable, string-literal discriminator so the error can be
+ * recognized reliably across extension bundle boundaries, where `instanceof` may fail because
+ * each bundle can load its own copy of this class. Prefer {@link isPackageVersionLookupNotSupportedError}
+ * over a bare `instanceof` check for that reason.
+ */
+class PackageVersionLookupNotSupportedError extends Error {
+    constructor(message) {
+        super(message ?? 'The package manager does not support looking up available package versions.');
+        /**
+         * Stable discriminator identifying this error type across bundle boundaries.
+         */
+        this.code = 'PackageVersionLookupNotSupported';
+        this.name = 'PackageVersionLookupNotSupportedError';
+        // Preserve the prototype chain when this class is transpiled to older targets so that
+        // `instanceof` continues to work within a single bundle.
+        Object.setPrototypeOf(this, PackageVersionLookupNotSupportedError.prototype);
+    }
+}
+exports.PackageVersionLookupNotSupportedError = PackageVersionLookupNotSupportedError;
+/**
+ * Type guard reporting whether an error represents unsupported package version lookup.
+ *
+ * Uses the stable {@link PackageVersionLookupNotSupportedError.code} discriminator, so it returns
+ * `true` even when the error crossed an extension bundle boundary and `instanceof` would fail.
+ *
+ * @param error The value to test.
+ * @returns `true` if `error` is a {@link PackageVersionLookupNotSupportedError} (or a structurally
+ *          equivalent error carrying the same `code`).
+ */
+function isPackageVersionLookupNotSupportedError(error) {
+    return (error instanceof PackageVersionLookupNotSupportedError ||
+        (typeof error === 'object' &&
+            error !== null &&
+            'code' in error &&
+            error.code === 'PackageVersionLookupNotSupported'));
+}

package/out/{main.js → cjs/types.js}

@@ -2,8 +2,7 @@
 // Copyright (c) Microsoft Corporation. All rights reserved.
 // Licensed under the MIT License.
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.PythonEnvironments = exports.EXTENSION_ID = exports.PackageChangeKind = exports.EnvironmentChangeKind = void 0;
-const vscode_1 = require("vscode");
+exports.PackageChangeKind = exports.EnvironmentChangeKind = void 0;
 /**
  * Enum representing the kinds of environment changes.
  */
@@ -32,23 +31,3 @@ var PackageChangeKind;
      */
     PackageChangeKind["remove"] = "remove";
 })(PackageChangeKind || (exports.PackageChangeKind = PackageChangeKind = {}));
-exports.EXTENSION_ID = 'ms-python.vscode-python-envs';
-// eslint-disable-next-line @typescript-eslint/no-namespace
-var PythonEnvironments;
-(function (PythonEnvironments) {
-    /**
-     * Returns the API exposed by the Python Environments extension in VS Code.
-     */
-    async function api() {
-        const extension = vscode_1.extensions.getExtension(exports.EXTENSION_ID);
-        if (extension === undefined) {
-            throw new Error(`Python Environments extension is not installed or is disabled`);
-        }
-        if (!extension.isActive) {
-            await extension.activate();
-        }
-        const pythonEnvsApi = extension.exports;
-        return pythonEnvsApi;
-    }
-    PythonEnvironments.api = api;
-})(PythonEnvironments || (exports.PythonEnvironments = PythonEnvironments = {}));

package/out/esm/main.mjs

@@ -0,0 +1,35 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+import { extensions } from 'vscode';
+/*
+ * Do not introduce any breaking changes to this API.
+ * This is the public API for other extensions to interact with the Python Environments extension.
+ *
+ * This module is a small public runtime/package facade: it re-exports all public type contracts
+ * from `./types` and the concrete error/guard from `./publicErrors`, and hosts the runtime surface
+ * (`EXTENSION_ID` and `PythonEnvironments.api()`).
+ */
+export * from './types.js';
+export * from './publicErrors.js';
+export const EXTENSION_ID = 'ms-python.vscode-python-envs';
+export var PythonEnvironments;
+(function (PythonEnvironments) {
+    /**
+     * Returns the API exposed by the Python Environments extension in VS Code.
+     */
+    async function api() {
+        const extension = extensions.getExtension(EXTENSION_ID);
+        if (extension === undefined) {
+            throw new Error(`Python Environments extension (${EXTENSION_ID}) is not installed or is disabled`);
+        }
+        if (!extension.isActive) {
+            await extension.activate();
+        }
+        const api = extension.exports;
+        if (!api) {
+            throw new Error(`Python Environments extension (${EXTENSION_ID}) did not expose its API. Ensure "python.useEnvironmentsExtension" is enabled and reload the window.`);
+        }
+        return api;
+    }
+    PythonEnvironments.api = api;
+})(PythonEnvironments || (PythonEnvironments = {}));

package/out/esm/package.json

@@ -0,0 +1 @@
+{"type":"module"}

package/out/esm/publicErrors.js

@@ -0,0 +1,50 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+/*
+ * Concrete, public runtime error type(s) for the Python Environments API.
+ * Kept separate from `./types.ts` (pure contracts) and re-exported from `./api.ts` to keep
+ * that facade small.
+ */
+/**
+ * Error thrown when a package manager cannot list available package versions.
+ *
+ * This distinguishes an *unsupported capability* from an *operational failure* (such as a
+ * failed command, a network error, or malformed/unparseable output). Consumers of
+ * {@link PythonPackageGetterApi.getPackageAvailableVersions} should treat this specific error
+ * as a signal to fall back to manual version entry, while letting any other error propagate.
+ *
+ * The {@link code} property carries a stable, string-literal discriminator so the error can be
+ * recognized reliably across extension bundle boundaries, where `instanceof` may fail because
+ * each bundle can load its own copy of this class. Prefer {@link isPackageVersionLookupNotSupportedError}
+ * over a bare `instanceof` check for that reason.
+ */
+export class PackageVersionLookupNotSupportedError extends Error {
+    constructor(message) {
+        super(message ?? 'The package manager does not support looking up available package versions.');
+        /**
+         * Stable discriminator identifying this error type across bundle boundaries.
+         */
+        this.code = 'PackageVersionLookupNotSupported';
+        this.name = 'PackageVersionLookupNotSupportedError';
+        // Preserve the prototype chain when this class is transpiled to older targets so that
+        // `instanceof` continues to work within a single bundle.
+        Object.setPrototypeOf(this, PackageVersionLookupNotSupportedError.prototype);
+    }
+}
+/**
+ * Type guard reporting whether an error represents unsupported package version lookup.
+ *
+ * Uses the stable {@link PackageVersionLookupNotSupportedError.code} discriminator, so it returns
+ * `true` even when the error crossed an extension bundle boundary and `instanceof` would fail.
+ *
+ * @param error The value to test.
+ * @returns `true` if `error` is a {@link PackageVersionLookupNotSupportedError} (or a structurally
+ *          equivalent error carrying the same `code`).
+ */
+export function isPackageVersionLookupNotSupportedError(error) {
+    return (error instanceof PackageVersionLookupNotSupportedError ||
+        (typeof error === 'object' &&
+            error !== null &&
+            'code' in error &&
+            error.code === 'PackageVersionLookupNotSupported'));
+}

package/out/esm/types.js

@@ -0,0 +1,30 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+/**
+ * Enum representing the kinds of environment changes.
+ */
+export var EnvironmentChangeKind;
+(function (EnvironmentChangeKind) {
+    /**
+     * Indicates that an environment was added.
+     */
+    EnvironmentChangeKind["add"] = "add";
+    /**
+     * Indicates that an environment was removed.
+     */
+    EnvironmentChangeKind["remove"] = "remove";
+})(EnvironmentChangeKind || (EnvironmentChangeKind = {}));
+/**
+ * Enum representing the kinds of package changes.
+ */
+export var PackageChangeKind;
+(function (PackageChangeKind) {
+    /**
+     * Indicates that a package was added.
+     */
+    PackageChangeKind["add"] = "add";
+    /**
+     * Indicates that a package was removed.
+     */
+    PackageChangeKind["remove"] = "remove";
+})(PackageChangeKind || (PackageChangeKind = {}));

package/out/types/main.d.ts

@@ -0,0 +1,10 @@
+import type { PythonEnvironmentApi } from './types.js';
+export * from './types.js';
+export * from './publicErrors.js';
+export declare const EXTENSION_ID = "ms-python.vscode-python-envs";
+export declare namespace PythonEnvironments {
+    /**
+     * Returns the API exposed by the Python Environments extension in VS Code.
+     */
+    function api(): Promise<PythonEnvironmentApi>;
+}

package/out/types/publicErrors.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Error thrown when a package manager cannot list available package versions.
+ *
+ * This distinguishes an *unsupported capability* from an *operational failure* (such as a
+ * failed command, a network error, or malformed/unparseable output). Consumers of
+ * {@link PythonPackageGetterApi.getPackageAvailableVersions} should treat this specific error
+ * as a signal to fall back to manual version entry, while letting any other error propagate.
+ *
+ * The {@link code} property carries a stable, string-literal discriminator so the error can be
+ * recognized reliably across extension bundle boundaries, where `instanceof` may fail because
+ * each bundle can load its own copy of this class. Prefer {@link isPackageVersionLookupNotSupportedError}
+ * over a bare `instanceof` check for that reason.
+ */
+export declare class PackageVersionLookupNotSupportedError extends Error {
+    /**
+     * Stable discriminator identifying this error type across bundle boundaries.
+     */
+    readonly code = "PackageVersionLookupNotSupported";
+    constructor(message?: string);
+}
+/**
+ * Type guard reporting whether an error represents unsupported package version lookup.
+ *
+ * Uses the stable {@link PackageVersionLookupNotSupportedError.code} discriminator, so it returns
+ * `true` even when the error crossed an extension bundle boundary and `instanceof` would fail.
+ *
+ * @param error The value to test.
+ * @returns `true` if `error` is a {@link PackageVersionLookupNotSupportedError} (or a structurally
+ *          equivalent error carrying the same `code`).
+ */
+export declare function isPackageVersionLookupNotSupportedError(error: unknown): error is PackageVersionLookupNotSupportedError;

package/out/{main.d.ts → types/types.d.ts}

@@ -1,4 +1,6 @@
-import { Disposable, Event, FileChangeType, LogOutputChannel, MarkdownString, TaskExecution, Terminal, TerminalOptions, ThemeIcon, Uri } from 'vscode';
+import type { Pep440Version } from '@renovatebot/pep440';
+import type { Disposable, Event, FileChangeType, LogOutputChannel, MarkdownString, RelativePattern, TaskExecution, Terminal, TerminalOptions, ThemeIcon, Uri } from 'vscode';
+export type { Pep440Version } from '@renovatebot/pep440';
 /**
  * The path to an icon, or a theme-specific configuration of icons.
  */
@@ -274,6 +276,16 @@ export interface QuickCreateConfig {
      */
     readonly detail?: string;
 }
+/**
+ * Options controlling environment removal.
+ */
+export interface RemoveEnvironmentOptions {
+    /**
+     * When `true`, removes the environment without prompting for confirmation.
+     * Intended for automated or headless scenarios. Defaults to `false`.
+     */
+    runHeadless?: boolean;
+}
 /**
  * Interface representing an environment manager.
  *
@@ -345,7 +357,7 @@ export interface EnvironmentManager {
      * Invoked to delete the given environment. Typical triggers include an explicit user
      * action (such as a "Delete Environment" command) and programmatic removal via the API.
      */
-    remove?(environment: PythonEnvironment): Promise<void>;
+    remove?(environment: PythonEnvironment, options?: RemoveEnvironmentOptions): Promise<void>;
     /**
      * Refreshes the list of Python environments within the specified scope.
      * @param scope - The scope within which to refresh environments.
@@ -402,24 +414,21 @@ export interface EnvironmentManager {
      */
     onDidChangeEnvironment?: Event<DidChangeEnvironmentEventArgs>;
     /**
-     * Resolves the specified Python environment. The environment can be either a {@link PythonEnvironment} or a {@link Uri} context.
+     * Resolves the Python environment associated with the specified URI context.
      *
-     * This method is used to obtain a fully detailed {@link PythonEnvironment} object. The input can be:
-     * - A {@link PythonEnvironment} object, which might be missing key details such as {@link PythonEnvironment.execInfo}.
-     * - A {@link Uri} object, which typically represents either:
-     *   - A folder that contains the Python environment.
-     *   - The path to a Python executable.
+     * This method is used to obtain a fully detailed {@link PythonEnvironment} object. The input
+     * URI typically represents either a folder that contains the Python environment or the path to
+     * a Python executable.
      *
-     * @param context - The context for resolving the environment, which can be a {@link PythonEnvironment} or a {@link Uri}.
+     * @param context - The URI context for resolving the environment.
      * @returns A promise that resolves to the fully detailed {@link PythonEnvironment}, or `undefined` if the environment cannot be resolved.
      *
      * @remarks
-     * Called to turn a lightly-populated {@link PythonEnvironment} or a {@link Uri}
-     * pointing at an interpreter or environment folder into a fully-populated
-     * {@link PythonEnvironment} with complete {@link PythonEnvironment.execInfo}. Typical
-     * triggers include the user manually selecting an interpreter path, resolving
-     * `python.defaultInterpreterPath` at startup, and populating execution details before
-     * launching Python.
+     * Called to turn a {@link Uri} pointing at an interpreter or environment folder into a
+     * fully-populated {@link PythonEnvironment} with complete {@link PythonEnvironment.execInfo}.
+     * Typical triggers include the user manually selecting an interpreter path, resolving
+     * `python.defaultInterpreterPath` at startup, and populating execution details before launching
+     * Python.
      */
     resolve(context: ResolveEnvironmentContext): Promise<PythonEnvironment | undefined>;
     /**
@@ -484,6 +493,10 @@ export interface PackageInfo {
      * The URIs associated with the package.
      */
     readonly uris?: readonly Uri[];
+    /**
+     * Whether the package is a transitive dependency.
+     */
+    readonly isTransitive?: boolean;
 }
 /**
  * Interface representing a package.
@@ -571,18 +584,79 @@ export interface PackageManager {
     /**
      * Retrieves the list of packages for the specified Python environment.
      * @param environment - The Python environment for which to retrieve packages.
+     * @param options - Optional settings for package retrieval.
      * @returns An array of packages, or undefined if the packages could not be retrieved.
      */
-    getPackages(environment: PythonEnvironment): Promise<Package[] | undefined>;
+    getPackages(environment: PythonEnvironment, options?: GetPackagesOptions): Promise<Package[] | undefined>;
+    /**
+     * Returns additional filesystem patterns to watch for package install/uninstall changes.
+     *
+     * These patterns are appended to the default site-packages metadata locations.
+     * Implement this for manager-specific locations (for example, conda-meta).
+     *
+     * @param environment - The Python environment whose package paths should be watched.
+     * @returns Relative patterns to watch for package changes.
+     */
+    getPackageWatchTargets?(environment: PythonEnvironment): RelativePattern[];
     /**
      * Event that is fired when packages change.
      */
     onDidChangePackages?: Event<DidChangePackagesEventArgs>;
+    /**
+     * Fetches the names of direct (non-transitive) packages for the specified Python environment.
+     *
+     * **Caveat:** Most package managers cannot track user install intent. For pip, this uses
+     * `pip list --not-required` which returns packages with no installed dependents (leaf packages),
+     * not necessarily packages the user explicitly installed. For example, if a user runs
+     * `pip install flask werkzeug`, werkzeug will still be reported as transitive because flask
+     * depends on it. This is a best-effort approximation.
+     *
+     * @param environment - The Python environment for which to fetch direct package names.
+     * @returns A promise that resolves to a set of package name strings, or undefined if not supported.
+     */
+    getDirectPackageNames?(environment: PythonEnvironment): Promise<Set<string> | undefined>;
     /**
      * Clears the package manager's cache.
      * @returns A promise that resolves when the cache is cleared.
      */
     clearCache?(): Promise<void>;
+    /**
+     * Returns the version of the underlying package management tool (e.g., pip, uv, conda).
+     * @param environment - The Python environment context.
+     * @returns A promise that resolves to a {@link Pep440Version} object, or `undefined` if not available.
+     */
+    getVersion?(environment: PythonEnvironment): Promise<Pep440Version | undefined>;
+    /**
+     * Retrieves the list of available versions for a given package, newest first.
+     *
+     * Implementations should:
+     * - resolve to an array of {@link Pep440Version} objects on success;
+     * - throw a {@link PackageVersionLookupNotSupportedError} when this manager cannot look up
+     *   versions at all (an unsupported capability);
+     * - let operational failures (command, network, or malformed/unparseable output) propagate
+     *   instead of swallowing them into `undefined`.
+     *
+     * Resolving to `undefined` is treated by callers as an unsupported capability, equivalent to
+     * throwing {@link PackageVersionLookupNotSupportedError}.
+     *
+     * @param environment - The Python environment context for the lookup.
+     * @param packageName - The name of the package to look up.
+     * @returns A promise that resolves to an array of {@link Pep440Version} objects (newest first).
+     * @throws {@link PackageVersionLookupNotSupportedError} when version lookup is unsupported.
+     */
+    getPackageAvailableVersions?(environment: PythonEnvironment, packageName: string): Promise<Pep440Version[] | undefined>;
+    /**
+     * Formats a versioned install specification for this package manager.
+     *
+     * Different package managers use different syntax (e.g. pip uses `name==version`,
+     * conda uses `name=version`). Implement this method to return the correct format.
+     * When absent, callers should default to `name==version`.
+     *
+     * @param packageName - The name of the package.
+     * @param version - The version string.
+     * @returns The install specification string (e.g. `"requests==2.31.0"` or `"requests=2.31.0"`).
+     */
+    formatInstallSpec?(packageName: string, version: string): string;
 }
 /**
  * Interface representing a Python project.
@@ -670,7 +744,30 @@ export interface DidChangePythonProjectsEventArgs {
      */
     removed: PythonProject[];
 }
-export type PackageManagementOptions = {
+/**
+ * Options for retrieving packages from a package manager.
+ */
+export interface GetPackagesOptions {
+    /**
+     * When `true`, bypasses the cache and fetches the latest packages from the underlying tool.
+     * Defaults to `false`.
+     */
+    skipCache?: boolean;
+}
+/**
+ * Options controlling user interaction during package management operations.
+ */
+export interface PackageManagementInteractionOptions {
+    /**
+     * When `true`, the package management operation runs without any user prompts or
+     * interaction and relies solely on the packages provided in the options. Any step
+     * that would normally require user input — such as selecting packages to install
+     * when none are specified — is skipped instead of prompting the user. Intended for
+     * automated or headless scenarios such as integration tests. Defaults to `false`.
+     */
+    runHeadless?: boolean;
+}
+export type PackageManagementOptions = PackageManagementInteractionOptions & ({
     /**
      * Upgrade the packages if they are already installed.
      */
@@ -704,7 +801,7 @@ export type PackageManagementOptions = {
      * The list of packages to uninstall.
      */
     uninstall: string[];
-};
+});
 /**
  * Options for creating a Python environment.
  */
@@ -758,9 +855,8 @@ export interface PythonEnvironmentManagerRegistrationApi {
      *
      * @param manager Environment Manager implementation to register.
      * @param options Optional registration options.
-     * @param options.extensionId The extension ID of the calling extension. This is used as a fallback when
-     * automatic extension detection fails, such as during F5 debugging where the extension's file path
-     * does not contain its marketplace ID. If automatic detection succeeds, this value is ignored.
+     * @param options.extensionId The extension ID of the calling extension. When this is not specified,
+     * or when the specified extension cannot be found, the extension ID will be automatically detected.
      * @returns A disposable that can be used to unregister the environment manager.
      * @see {@link EnvironmentManager}
      */
@@ -792,9 +888,10 @@ export interface PythonEnvironmentManagementApi {
      * Remove a Python environment.
      *
      * @param environment The Python environment to remove.
+     * @param options Optional parameters controlling environment removal.
      * @returns A promise that resolves when the environment has been removed.
      */
-    removeEnvironment(environment: PythonEnvironment): Promise<void>;
+    removeEnvironment(environment: PythonEnvironment, options?: RemoveEnvironmentOptions): Promise<void>;
 }
 export interface PythonEnvironmentsApi {
     /**
@@ -815,10 +912,10 @@ export interface PythonEnvironmentsApi {
      */
     onDidChangeEnvironments: Event<DidChangeEnvironmentsEventArgs>;
     /**
-     * This method is used to get the details missing from a PythonEnvironment. Like
-     * {@link PythonEnvironment.execInfo} and other details.
+     * This method is used to get the details for the Python environment associated with a URI
+     * context, such as an interpreter path or environment folder.
      *
-     * @param context : The PythonEnvironment or Uri for which details are required.
+     * @param context - The URI context for which environment details are required.
      */
     resolveEnvironment(context: ResolveEnvironmentContext): Promise<PythonEnvironment | undefined>;
 }
@@ -849,9 +946,8 @@ export interface PythonPackageManagerRegistrationApi {
      *
      * @param manager Package Manager implementation to register.
      * @param options Optional registration options.
-     * @param options.extensionId The extension ID of the calling extension. This is used as a fallback when
-     * automatic extension detection fails, such as during F5 debugging where the extension's file path
-     * does not contain its marketplace ID. If automatic detection succeeds, this value is ignored.
+     * @param options.extensionId The extension ID of the calling extension. When this is not specified,
+     * or when the specified extension cannot be found, the extension ID will be automatically detected.
      * @returns A disposable that can be used to unregister the package manager.
      * @see {@link PackageManager}
      */
@@ -859,6 +955,21 @@ export interface PythonPackageManagerRegistrationApi {
         extensionId?: string;
     }): Disposable;
 }
+/**
+ * Controls how package version lookup failures are reported.
+ */
+export interface GetPackageAvailableVersionsOptions {
+    /**
+     * Determines whether lookup failures preserve the legacy `undefined` result or reject.
+     *
+     * - `legacy` resolves to `undefined` for unsupported lookups and operational failures.
+     *   This remains the default for backward compatibility, but may be removed in a future
+     *   major API version.
+     * - `throw` rejects with {@link PackageVersionLookupNotSupportedError} for unsupported
+     *   lookups and propagates operational failures unchanged.
+     */
+    errorMode?: 'legacy' | 'throw';
+}
 export interface PythonPackageGetterApi {
     /**
      * Refresh the list of packages in a Python Environment.
@@ -871,9 +982,28 @@ export interface PythonPackageGetterApi {
      * Get the list of packages in a Python Environment.
      *
      * @param environment The Python Environment for which the list of packages is required.
+     * @param options Optional settings for package retrieval.
      * @returns The list of packages in the Python Environment.
      */
-    getPackages(environment: PythonEnvironment): Promise<Package[] | undefined>;
+    getPackages(environment: PythonEnvironment, options?: GetPackagesOptions): Promise<Package[] | undefined>;
+    /**
+     * Get the list of available versions for a package, newest first.
+     *
+     * By default, this preserves the legacy behavior of resolving to `undefined` for unsupported
+     * lookups and operational failures. Pass `{ errorMode: 'throw' }` to distinguish unsupported
+     * capabilities from operational failures: unsupported lookups reject with
+     * {@link PackageVersionLookupNotSupportedError}, while other failures propagate unchanged.
+     *
+     * @param environment The Python Environment context for the lookup.
+     * @param packageName The name of the package to look up.
+     * @param options Controls how lookup failures are reported.
+     * @returns A promise that resolves to an array of {@link Pep440Version} objects (newest first),
+     *          or `undefined` in legacy mode when lookup is unsupported or fails.
+     */
+    getPackageAvailableVersions(environment: PythonEnvironment, packageName: string, options: GetPackageAvailableVersionsOptions & {
+        errorMode: 'throw';
+    }): Promise<Pep440Version[]>;
+    getPackageAvailableVersions(environment: PythonEnvironment, packageName: string, options?: GetPackageAvailableVersionsOptions): Promise<Pep440Version[] | undefined>;
     /**
      * Event raised when the list of packages in a Python Environment changes.
      * @see {@link DidChangePackagesEventArgs}
@@ -1079,7 +1209,9 @@ export interface PythonBackgroundRunOptions {
      */
     args: string[];
     /**
-     * Current working directory for the script or module. Default is the project directory for the script being run.
+     * Current working directory for the script or module. This is passed directly to the spawned
+     * process; when it is omitted the process inherits the extension host's working directory,
+     * which is not the project directory. Supply this when the script resolves relative paths.
      */
     cwd?: string;
     /**
@@ -1143,10 +1275,3 @@ export interface PythonEnvironmentVariablesApi {
  */
 export interface PythonEnvironmentApi extends PythonEnvironmentManagerApi, PythonPackageManagerApi, PythonProjectApi, PythonExecutionApi, PythonEnvironmentVariablesApi {
 }
-export declare const EXTENSION_ID = "ms-python.vscode-python-envs";
-export declare namespace PythonEnvironments {
-    /**
-     * Returns the API exposed by the Python Environments extension in VS Code.
-     */
-    function api(): Promise<PythonEnvironmentApi>;
-}

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "@vscode/python-environments",
     "description": "An API facade for the Python Environments extension in VS Code",
-    "version": "1.0.0",
+    "version": "1.4.0",
     "author": {
         "name": "Microsoft Corporation"
     },
@@ -11,8 +11,18 @@
         "API",
         "Environments"
     ],
-    "main": "./out/main.js",
-    "types": "./out/main.d.ts",
+    "main": "./out/cjs/main.cjs",
+    "types": "./out/types/main.d.ts",
+    "exports": {
+        "import": {
+            "types": "./out/types/main.d.ts",
+            "default": "./out/esm/main.mjs"
+        },
+        "require": {
+            "types": "./out/types/main.d.ts",
+            "default": "./out/cjs/main.cjs"
+        }
+    },
     "engines": {
         "node": ">=22.21.1",
         "vscode": "^1.110.0"
@@ -29,13 +39,23 @@
     "scripts": {
         "prepublishOnly": "echo \"⛔ Can only publish from a secure pipeline ⛔\" && node -e \"process.exitCode = 1\"",
         "prepack": "npm run all:publish",
-        "all:publish": "git clean -xfd . && npm install && npm run compile",
-        "compile": "tsc -b ./tsconfig.json",
-        "clean": "node -e \"const fs = require('fs'); fs.rmSync('./out', { recursive: true, force: true });\""
+        "all:publish": "git clean -xfd . && npm install && npm run copy:sources && npm run compile",
+        "copy:sources": "node ./scripts/copy-sources.cjs",
+        "compile": "npm run clean && npm run compile:types && npm run compile:esm && npm run compile:cjs",
+        "compile:types": "tsc -b ./tsconfig.types.json",
+        "compile:esm": "tsc -b ./tsconfig.esm.json && mve out/esm/main.js out/esm/main.mjs && node -e \"require('fs').writeFileSync('out/esm/package.json', '{\\\"type\\\":\\\"module\\\"}')\"",
+        "compile:cjs": "tsc -b ./tsconfig.cjs.json && mve out/cjs/main.js out/cjs/main.cjs",
+        "clean": "node -e \"const fs = require('fs'); fs.rmSync('./out', { recursive: true, force: true });\"",
+        "test": "npm run test:package",
+        "test:package": "node ./scripts/test-package.cjs"
     },
     "devDependencies": {
         "@types/node": "^22.0.0",
         "@types/vscode": "^1.99.0",
+        "mve": "^0.1.2",
         "typescript": "^5.1.3"
+    },
+    "dependencies": {
+        "@renovatebot/pep440": "^3.1.0"
     }
 }