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

src/common/lockfile.apis.ts

@@ -0,0 +1,135 @@
+// 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';
+
+/** 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 (isAlreadyExistsError(error)) {
+                            return;
+                        }
+                        try {
+                            await fsapi.rename(ownerMarker, retainedMarker);
+                        } catch (renameError) {
+                            if (!isAlreadyExistsError(renameError)) {
+                                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 (isFileNotFoundError(error)) {
+                            throw createLockError('Lock ownership was compromised', 'ECOMPROMISED', lockPath);
+                        }
+                        throw error;
+                    }
+                    await fsapi.rmdir(lockPath);
+                },
+            };
+        } catch (error) {
+            if (!isAlreadyExistsError(error)) {
+                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())));
+        }
+    }
+}
+
+function isAlreadyExistsError(error: unknown): boolean {
+    return hasErrorCode(error, 'EEXIST');
+}
+
+function isFileNotFoundError(error: unknown): boolean {
+    return hasErrorCode(error, 'ENOENT');
+}
+
+async function isRetainedLock(lockPath: string): Promise<boolean> {
+    try {
+        await fsapi.lstat(path.join(lockPath, 'retained'));
+        return true;
+    } catch (error) {
+        if (isFileNotFoundError(error)) {
+            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));
+}
+
+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';

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

@@ -66,40 +66,14 @@ export async function runUV(
     token?: CancellationToken,
     timeout?: number,
 ): Promise<string> {
-    log?.info(`Running: uv ${args.join(' ')}`);
-    return new Promise<string>((resolve, reject) => {
-        const spawnOptions: { cwd?: string; timeout?: number } = { cwd };
-        if (timeout !== undefined) {
-            spawnOptions.timeout = timeout;
-        }
-        const proc = spawnProcess('uv', args, spawnOptions);
-        token?.onCancellationRequested(() => {
-            proc.kill();
-            reject(new CancellationError());
-        });
-
-        proc.on('error', (err) => {
-            log?.error(`Error spawning uv: ${err}`);
-            reject(new Error(`Error spawning uv: ${err.message}`));
-        });
-
-        let builder = '';
-        proc.stdout?.on('data', (data) => {
-            const s = data.toString('utf-8');
-            builder += s;
-            log?.append(s);
-        });
-        proc.stderr?.on('data', (data) => {
-            log?.append(data.toString('utf-8'));
-        });
-        proc.on('close', () => {
-            resolve(builder);
-        });
-        proc.on('exit', (code) => {
-            if (code !== 0) {
-                reject(new Error(`Failed to run uv ${args.join(' ')}`));
-            }
-        });
+    return runProcess('uv', args, {
+        cwd,
+        displayName: 'uv',
+        log,
+        token,
+        timeout,
+        collectStderr: false,
+        logPrefix: '',
     });
 }
 
@@ -111,37 +85,75 @@ export async function runPython(
     token?: CancellationToken,
     timeout?: number,
 ): Promise<string> {
-    log?.info(`Running: ${python} ${args.join(' ')}`);
+    return runProcess(python, args, {
+        cwd,
+        displayName: 'python',
+        log,
+        token,
+        timeout,
+        collectStderr: true,
+        logPrefix: 'python: ',
+    });
+}
+
+function runProcess(executable: string, args: string[], options: RunProcessOptions): Promise<string> {
+    options.log?.info(`Running: ${executable} ${args.join(' ')}`);
     return new Promise<string>((resolve, reject) => {
-        const proc = spawnProcess(python, args, { cwd: cwd, timeout });
-        token?.onCancellationRequested(() => {
-            proc.kill();
+        const spawnOptions: { cwd?: string; timeout?: number } = { cwd: options.cwd };
+        if (options.timeout !== undefined) {
+            spawnOptions.timeout = options.timeout;
+        }
+        const proc = spawnProcess(executable, args, spawnOptions);
+        let cancellationRequested = false;
+        options.token?.onCancellationRequested(() => {
+            cancellationRequested = true;
+            try {
+                proc.kill();
+            } catch {
+                // Preserve cancellation when signaling fails.
+            }
             reject(new CancellationError());
         });
 
         proc.on('error', (err) => {
-            log?.error(`Error spawning python: ${err}`);
-            reject(new Error(`Error spawning python: ${err.message}`));
+            if (cancellationRequested) {
+                reject(new CancellationError());
+                return;
+            }
+            options.log?.error(`Error spawning ${options.displayName}: ${err}`);
+            reject(new Error(`Error spawning ${options.displayName}: ${err.message}`));
         });
 
         let builder = '';
         proc.stdout?.on('data', (data) => {
             const s = data.toString('utf-8');
             builder += s;
-            log?.append(`python: ${s}`);
+            options.log?.append(`${options.logPrefix}${s}`);
         });
         proc.stderr?.on('data', (data) => {
             const s = data.toString('utf-8');
-            builder += s;
-            log?.append(`python: ${s}`);
+            if (options.collectStderr) {
+                builder += s;
+            }
+            options.log?.append(`${options.logPrefix}${s}`);
         });
         proc.on('close', () => {
             resolve(builder);
         });
         proc.on('exit', (code) => {
             if (code !== 0) {
-                reject(new Error(`Failed to run python ${args.join(' ')}`));
+                reject(new Error(`Failed to run ${options.displayName} ${args.join(' ')}`));
             }
         });
     });
 }
+
+interface RunProcessOptions {
+    readonly cwd?: string;
+    readonly displayName: 'python' | 'uv';
+    readonly log?: LogOutputChannel;
+    readonly token?: CancellationToken;
+    readonly timeout?: number;
+    readonly collectStderr: boolean;
+    readonly logPrefix: string;
+}

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,14 @@ 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 interface CreateWithProgressOptions {
+    /** Whether to record uv-created environments in workspace state. Defaults to true. */
+    readonly trackUvEnvironment?: boolean;
 }
 
 export async function clearVenvCache(): Promise<void> {
@@ -340,9 +358,9 @@ export async function createWithProgress(
     venvRoot: Uri,
     envPath: string,
     packages?: PipPackages,
+    options?: CreateWithProgressOptions,
 ): 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 +401,7 @@ export async function createWithProgress(
                 const env = api.createPythonEnvironmentItem(await getPythonInfo(resolved), manager);
 
                 if (
+                    options?.trackUvEnvironment !== false &&
                     useUv &&
                     (resolved.kind === NativePythonEnvironmentKind.venvUv ||
                         resolved.kind === NativePythonEnvironmentKind.uvWorkspace)
@@ -401,6 +420,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;