Add generic environment-creation utilities (PEP 723 PR 5a/16)

src/common/lockfile.apis.ts

@@ -0,0 +1,127 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+
+import * as crypto from 'crypto';
+import * as fsapi from 'fs-extra';
+import * as path from 'path';
+
+export interface AcquireFileLockOptions {
+    readonly timeoutMs: number;
+    readonly retryIntervalMs: number;
+}
+
+export interface AcquiredFileLock {
+    readonly release: () => Promise<void>;
+    /** Keep the lock and make later acquisition attempts fail immediately. */
+    readonly retain: () => Promise<void>;
+}
+
+type LockState = 'held' | 'released' | 'retained';
+
+/** Acquire an atomic lock released only explicitly; interrupted operations remain locked. */
+export async function acquireFileLock(filePath: string, options: AcquireFileLockOptions): Promise<AcquiredFileLock> {
+    const lockPath = `${path.resolve(filePath)}.lock`;
+    const ownerMarker = path.join(lockPath, `owner-${process.pid}-${crypto.randomBytes(16).toString('hex')}`);
+    const retainedMarker = path.join(lockPath, 'retained');
+    const deadline = Date.now() + options.timeoutMs;
+
+    while (true) {
+        try {
+            await fsapi.mkdir(lockPath);
+            try {
+                await fsapi.writeFile(ownerMarker, '', { flag: 'wx' });
+            } catch (error) {
+                try {
+                    await fsapi.rmdir(lockPath);
+                } catch {
+                    throw createLockError(
+                        'Lock initialization failed and left an owner-less lock directory',
+                        'ELOCKORPHANED',
+                        lockPath,
+                    );
+                }
+                throw error;
+            }
+
+            let state: LockState = 'held';
+            return {
+                retain: async () => {
+                    if (state !== 'held') {
+                        return;
+                    }
+                    state = 'retained';
+                    try {
+                        await fsapi.writeFile(retainedMarker, '', { flag: 'wx' });
+                    } catch (error) {
+                        if (hasErrorCode(error, 'EEXIST')) {
+                            return;
+                        }
+                        try {
+                            await fsapi.rename(ownerMarker, retainedMarker);
+                        } catch (renameError) {
+                            if (!hasErrorCode(renameError, 'EEXIST')) {
+                                throw createLockError(
+                                    'Failed to mark the lock as retained',
+                                    'ERETAINFAILED',
+                                    lockPath,
+                                );
+                            }
+                        }
+                    }
+                },
+                release: async () => {
+                    if (state !== 'held') {
+                        return;
+                    }
+                    state = 'released';
+                    try {
+                        await fsapi.unlink(ownerMarker);
+                    } catch (error) {
+                        if (hasErrorCode(error, 'ENOENT')) {
+                            throw createLockError('Lock ownership was compromised', 'ECOMPROMISED', lockPath);
+                        }
+                        throw error;
+                    }
+                    await fsapi.rmdir(lockPath);
+                },
+            };
+        } catch (error) {
+            if (!hasErrorCode(error, 'EEXIST')) {
+                throw error;
+            }
+            if (await isRetainedLock(lockPath)) {
+                throw createLockError('Lock was retained after an interrupted operation', 'ELOCKRETAINED', lockPath);
+            }
+            if (Date.now() >= deadline) {
+                throw createLockError('Lock is already being held', 'ELOCKED', lockPath);
+            }
+            await delay(Math.min(options.retryIntervalMs, Math.max(0, deadline - Date.now())));
+        }
+    }
+}
+
+async function isRetainedLock(lockPath: string): Promise<boolean> {
+    try {
+        await fsapi.lstat(path.join(lockPath, 'retained'));
+        return true;
+    } catch (error) {
+        if (hasErrorCode(error, 'ENOENT')) {
+            return false;
+        }
+        throw error;
+    }
+}
+
+function hasErrorCode(error: unknown, code: string): boolean {
+    return (
+        typeof error === 'object' && error !== null && 'code' in error && (error as NodeJS.ErrnoException).code === code
+    );
+}
+
+function createLockError(message: string, code: string, lockPath: string): NodeJS.ErrnoException {
+    return Object.assign(new Error(message), { code, path: lockPath });
+}
+
+async function delay(milliseconds: number): Promise<void> {
+    return new Promise((resolve) => setTimeout(resolve, milliseconds));
+}

src/common/utils/virtualEnvironment.ts

@@ -0,0 +1,11 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+
+import * as path from 'path';
+import { isWindows } from './platformUtils';
+
+export function getVenvPythonPath(envPath: string): string {
+    return isWindows()
+        ? path.join(envPath, 'Scripts', 'python.exe')
+        : path.join(envPath, 'bin', 'python');
+}

src/managers/builtin/helpers.ts

@@ -73,12 +73,22 @@ export async function runUV(
             spawnOptions.timeout = timeout;
         }
         const proc = spawnProcess('uv', args, spawnOptions);
+        let cancellationRequested = false;
         token?.onCancellationRequested(() => {
-            proc.kill();
+            cancellationRequested = true;
+            try {
+                proc.kill();
+            } catch {
+                // Preserve cancellation when signaling fails.
+            }
             reject(new CancellationError());
         });
 
         proc.on('error', (err) => {
+            if (cancellationRequested) {
+                reject(new CancellationError());
+                return;
+            }
             log?.error(`Error spawning uv: ${err}`);
             reject(new Error(`Error spawning uv: ${err.message}`));
         });
@@ -114,12 +124,22 @@ export async function runPython(
     log?.info(`Running: ${python} ${args.join(' ')}`);
     return new Promise<string>((resolve, reject) => {
         const proc = spawnProcess(python, args, { cwd: cwd, timeout });
+        let cancellationRequested = false;
         token?.onCancellationRequested(() => {
-            proc.kill();
+            cancellationRequested = true;
+            try {
+                proc.kill();
+            } catch {
+                // Preserve cancellation when signaling fails.
+            }
             reject(new CancellationError());
         });
 
         proc.on('error', (err) => {
+            if (cancellationRequested) {
+                reject(new CancellationError());
+                return;
+            }
             log?.error(`Error spawning python: ${err}`);
             reject(new Error(`Error spawning python: ${err.message}`));
         });

src/managers/builtin/venvUtils.ts

@@ -1,7 +1,16 @@
 import * as fsapi from 'fs-extra';
 import * as os from 'os';
 import * as path from 'path';
-import { l10n, LogOutputChannel, ProgressLocation, QuickPickItem, QuickPickItemKind, ThemeIcon, Uri } from 'vscode';
+import {
+    CancellationError,
+    l10n,
+    LogOutputChannel,
+    ProgressLocation,
+    QuickPickItem,
+    QuickPickItemKind,
+    ThemeIcon,
+    Uri,
+} from 'vscode';
 import { EnvironmentManager, PythonEnvironment, PythonEnvironmentApi, PythonEnvironmentInfo } from '../../api';
 import { ENVS_EXTENSION_ID } from '../../common/constants';
 import { Common, VenvManagerStrings } from '../../common/localize';
@@ -10,6 +19,7 @@ import { getWorkspacePersistentState } from '../../common/persistentState';
 import { EventNames } from '../../common/telemetry/constants';
 import { sendTelemetryEvent } from '../../common/telemetry/sender';
 import { normalizePath } from '../../common/utils/pathUtils';
+import { getVenvPythonPath } from '../../common/utils/virtualEnvironment';
 import {
     showErrorMessage,
     showOpenDialog,
@@ -52,6 +62,9 @@ export interface CreateEnvironmentResult {
      * Exists if error occurred while installing packages and includes error description.
      */
     pkgInstallationErr?: string;
+
+    /** Cancellation may leave package processes running. */
+    pkgInstallationCancelled?: boolean;
 }
 
 export async function clearVenvCache(): Promise<void> {
@@ -340,9 +353,9 @@ export async function createWithProgress(
     venvRoot: Uri,
     envPath: string,
     packages?: PipPackages,
+    trackUvEnvironment = true,
 ): Promise<CreateEnvironmentResult | undefined> {
-    const pythonPath =
-        os.platform() === 'win32' ? path.join(envPath, 'Scripts', 'python.exe') : path.join(envPath, 'bin', 'python');
+    const pythonPath = getVenvPythonPath(envPath);
 
     return await withProgress(
         {
@@ -383,6 +396,7 @@ export async function createWithProgress(
                 const env = api.createPythonEnvironmentItem(await getPythonInfo(resolved), manager);
 
                 if (
+                    trackUvEnvironment &&
                     useUv &&
                     (resolved.kind === NativePythonEnvironmentKind.venvUv ||
                         resolved.kind === NativePythonEnvironmentKind.uvWorkspace)
@@ -401,6 +415,7 @@ export async function createWithProgress(
                     } catch (e) {
                         // error occurred while installing packages
                         result.pkgInstallationErr = e instanceof Error ? e.message : String(e);
+                        result.pkgInstallationCancelled = e instanceof CancellationError;
                     }
                 }
                 result.environment = env;