Merge branch 'main' into copilot/fix-3b6de93e-8dce-49f5-8cd1-5f79d0da7ad8

Author: eleanorjboyd

.github/instructions/testing-workflow.instructions.md

@@ -537,70 +537,17 @@ envConfig.inspect
 -   ❌ Tests that don't clean up mocks properly
 -   ❌ Overly complex test setup that's hard to understand
 
-## � Common Pitfalls & Fast Diagnosis
-
-These recurring issues have caused wasted cycles. Follow the quick diagnosis flow to avoid them:
-
-### 1. 0 Tests Detected When Filtering (e.g. with --grep or targeted run)
-
-Likely Causes (in order):
-
--   The TypeScript test file has not been compiled to `out/test/...` yet.
--   The file was moved outside the compiler `rootDir` (tsconfig sets `rootDir: src`), so `tsc` will not emit it into `out/`.
--   The grep / test name filter does not match the suite or test names.
-
-Diagnosis Checklist:
-
-1. Confirm compile step ran: if not in watch mode, run the compile test script (see below) **before** executing tests.
-2. Check for the emitted JS: derive the expected path (replace `src/` with `out/` and ensure the directory pattern matches `out/test/**/*.unit.test.js`). If the JS file is missing, it's a compilation / placement issue.
-3. Open the compiled JS and verify the `suite("<Your Suite Name>")` string literally appears; if missing, the source file wasn’t included or was misnamed.
-4. Re-run the test using the programmatic test tool (preferred) referencing the file path instead of a grep first; if that succeeds, refine your grep pattern.
-
-Remediation:
-
--   Ensure unit test files live under `src/test/...` (since `rootDir` is `src`) so they are emitted under `out/test/...` and picked up by Mocha’s spec glob.
--   Run `watch-tests` once (preferred) or a one-off `compile-tests` before first execution.
--   Avoid relocating tests to a top-level `test/` folder unless tsconfig and spec globs are updated accordingly.
-
-### 2. Using Terminal First Instead of Test Tool
-
-Always default to the test execution tool (runTests) for:
-
--   Precise targeting (single file / specific tests via testNames)
--   Richer integration & structured output
-
-Use terminal (`npm run unittest`) only as a fallback.
-
-### 3. Infinite Watch Confusion
-
-If you started `npm run watch-tests`, do **not** also run `compile-tests` repeatedly—watch already handles incremental builds. Just re-run the test tool after edits.
-
-### Quick Flowchart
-
-0 tests? → Was TS compiled? (Check for `out/test/...js`) → If no: compile. → If yes: Is file under `src/test`? → If no: relocate. → If yes: Does suite name match grep / filter? → Adjust filter → Use runTests with direct file path.
-
-### Example Programmatic Run
-
-```
-await runTests({
-    files: ['/absolute/path/to/src/test/features/execution/execUtils.unit.test.ts']
-});
-```
-
-If that returns 0, re-check compilation path mapping.
-
-## Agent Learning Patterns
-
-### Key Implementation Insights
+## 🧠 Agent Learnings
 
 -   Always use dynamic path construction with Node.js `path` module when testing functions that resolve paths against workspace folders to ensure cross-platform compatibility (1)
 -   Use `runTests` tool for programmatic test execution rather than terminal commands for better integration and result parsing (1)
--   Mock wrapper functions (e.g., `workspaceApis.getConfiguration()`) instead of VS Code APIs directly to avoid stubbing issues (1)
+-   Mock wrapper functions (e.g., `workspaceApis.getConfiguration()`) instead of VS Code APIs directly to avoid stubbing issues (2)
 -   Start compilation with `npm run watch-tests` before test execution to ensure TypeScript files are built (1)
--   Use `sinon.match()` patterns for resilient assertions that don't break on minor output changes (1)
+-   Use `sinon.match()` patterns for resilient assertions that don't break on minor output changes (2)
 -   Fix test issues iteratively - run tests, analyze failures, apply fixes, repeat until passing (1)
 -   When fixing mock environment creation, use `null` to truly omit properties rather than `undefined` (1)
 -   Always recompile TypeScript after making import/export changes before running tests, as stubs won't work if they're applied to old compiled JavaScript that doesn't have the updated imports (2)
 -   Create proxy abstraction functions for Node.js APIs like `cp.spawn` to enable clean testing - use function overloads to preserve Node.js's intelligent typing while making the functions mockable (1)
 -   When a targeted test run yields 0 tests, first verify the compiled JS exists under `out/test` (rootDir is `src`); absence almost always means the test file sits outside `src` or compilation hasn't run yet (1)
 -   When unit tests fail with VS Code API errors like `TypeError: X is not a constructor` or `Cannot read properties of undefined (reading 'Y')`, check if VS Code APIs are properly mocked in `/src/test/unittests.ts` - add missing Task-related APIs (`Task`, `TaskScope`, `ShellExecution`, `TaskRevealKind`, `TaskPanelKind`) and namespace mocks (`tasks`) following the existing pattern of `mockedVSCode.X = vscodeMocks.vscMockExtHostedTypes.X` (1)
+-   Create minimal mock objects with only required methods and use TypeScript type assertions (e.g., mockApi as PythonEnvironmentApi) to satisfy interface requirements instead of implementing all interface methods when only specific methods are needed for the test (1)

src/common/childProcess.apis.ts

@@ -0,0 +1,28 @@
+import * as cp from 'child_process';
+
+/**
+ * Spawns a new process using the specified command and arguments.
+ * This function abstracts cp.spawn to make it easier to mock in tests.
+ *
+ * When stdio: 'pipe' is used, returns ChildProcessWithoutNullStreams.
+ * Otherwise returns the standard ChildProcess.
+ */
+
+// Overload for stdio: 'pipe' - guarantees non-null streams
+export function spawnProcess(
+    command: string,
+    args: string[],
+    options: cp.SpawnOptions & { stdio: 'pipe' },
+): cp.ChildProcessWithoutNullStreams;
+
+// Overload for general case
+export function spawnProcess(command: string, args: string[], options?: cp.SpawnOptions): cp.ChildProcess;
+
+// Implementation - delegates to cp.spawn to preserve its typing magic
+export function spawnProcess(
+    command: string,
+    args: string[],
+    options?: cp.SpawnOptions,
+): cp.ChildProcess | cp.ChildProcessWithoutNullStreams {
+    return cp.spawn(command, args, options ?? {});
+}

src/features/execution/runInBackground.ts

@@ -1,5 +1,5 @@
-import * as cp from 'child_process';
 import { PythonBackgroundRunOptions, PythonEnvironment, PythonProcess } from '../../api';
+import { spawnProcess } from '../../common/childProcess.apis';
 import { traceError, traceInfo, traceWarn } from '../../common/logging';
 import { quoteStringIfNecessary } from './execUtils';
 
@@ -39,7 +39,11 @@ export async function runInBackground(
         traceWarn(`Error checking if executable exists: ${err instanceof Error ? err.message : String(err)}`);
     }
 
-    const proc = cp.spawn(executable, allArgs, { stdio: 'pipe', cwd: options.cwd, env: options.env });
+    const proc = spawnProcess(executable, allArgs, {
+        stdio: 'pipe',
+        cwd: options.cwd,
+        env: options.env,
+    });
 
     return {
         pid: proc.pid,

src/features/terminal/shells/bash/bashStartup.ts

@@ -5,7 +5,7 @@ import which from 'which';
 import { traceError, traceInfo, traceVerbose } from '../../../../common/logging';
 import { ShellConstants } from '../../../common/shellConstants';
 import { hasStartupCode, insertStartupCode, removeStartupCode } from '../common/editUtils';
-import { isWsl, shellIntegrationForActiveTerminal } from '../common/shellUtils';
+import { getShellIntegrationEnabledCache, isWsl, shellIntegrationForActiveTerminal } from '../common/shellUtils';
 import { ShellScriptEditState, ShellSetupState, ShellStartupScriptProvider } from '../startupProvider';
 import { BASH_ENV_KEY, BASH_OLD_ENV_KEY, BASH_SCRIPT_VERSION, ZSH_ENV_KEY, ZSH_OLD_ENV_KEY } from './bashConstants';
 
@@ -69,7 +69,8 @@ async function isStartupSetup(profile: string, key: string): Promise<ShellSetupS
     return ShellSetupState.NotSetup;
 }
 async function setupStartup(profile: string, key: string, name: string): Promise<boolean> {
-    if (shellIntegrationForActiveTerminal(name, profile) && !isWsl()) {
+    const shellIntegrationEnabled = await getShellIntegrationEnabledCache();
+    if ((shellIntegrationEnabled || (await shellIntegrationForActiveTerminal(name, profile))) && !isWsl()) {
         removeStartup(profile, key);
         return true;
     }

src/features/terminal/shells/common/shellUtils.ts

@@ -1,9 +1,15 @@
 import { PythonCommandRunConfiguration, PythonEnvironment } from '../../../../api';
 import { traceInfo } from '../../../../common/logging';
+import { getGlobalPersistentState } from '../../../../common/persistentState';
+import { sleep } from '../../../../common/utils/asyncUtils';
 import { isWindows } from '../../../../common/utils/platformUtils';
 import { activeTerminalShellIntegration } from '../../../../common/window.apis';
+import { getConfiguration } from '../../../../common/workspace.apis';
 import { ShellConstants } from '../../../common/shellConstants';
 import { quoteArgs } from '../../../execution/execUtils';
+import { SHELL_INTEGRATION_POLL_INTERVAL, SHELL_INTEGRATION_TIMEOUT } from '../../utils';
+
+export const SHELL_INTEGRATION_STATE_KEY = 'shellIntegration.enabled';
 
 function getCommandAsString(command: PythonCommandRunConfiguration[], shell: string, delimiter: string): string {
     const parts = [];
@@ -98,22 +104,60 @@ export function extractProfilePath(content: string): string | undefined {
     return undefined;
 }
 
-export function shellIntegrationForActiveTerminal(name: string, profile?: string): boolean {
-    const hasShellIntegration = activeTerminalShellIntegration();
+export async function shellIntegrationForActiveTerminal(name: string, profile?: string): Promise<boolean> {
+    let hasShellIntegration = activeTerminalShellIntegration();
+    let timeout = 0;
+
+    while (!hasShellIntegration && timeout < SHELL_INTEGRATION_TIMEOUT) {
+        await sleep(SHELL_INTEGRATION_POLL_INTERVAL);
+        timeout += SHELL_INTEGRATION_POLL_INTERVAL;
+        hasShellIntegration = activeTerminalShellIntegration();
+    }
 
     if (hasShellIntegration) {
         traceInfo(
-            `SHELL: Shell integration is available on your active terminal, with name ${name} and profile ${profile}. Python activate scripts will be evaluated at shell integration level, except in WSL.`
+            `SHELL: Shell integration is available on your active terminal, with name ${name} and profile ${profile}. Python activate scripts will be evaluated at shell integration level, except in WSL.`,
         );
+
+        // Update persistent storage to reflect that shell integration is available
+        const persistentState = await getGlobalPersistentState();
+        await persistentState.set(SHELL_INTEGRATION_STATE_KEY, true);
+
         return true;
     }
     return false;
 }
 
 export function isWsl(): boolean {
     // WSL sets these environment variables
-     return !!(process.env.WSL_DISTRO_NAME || 
-             process.env.WSL_INTEROP || 
-             process.env.WSLENV);
+    return !!(process.env.WSL_DISTRO_NAME || process.env.WSL_INTEROP || process.env.WSLENV);
 }
 
+export async function getShellIntegrationEnabledCache(): Promise<boolean> {
+    const persistentState = await getGlobalPersistentState();
+    const shellIntegrationInspect =
+        getConfiguration('terminal.integrated').inspect<boolean>('shellIntegration.enabled');
+
+    let shellIntegrationEnabled = true;
+    if (shellIntegrationInspect) {
+        // Priority: workspaceFolder > workspace > globalRemoteValue > globalLocalValue > global > default
+        const inspectValue = shellIntegrationInspect as Record<string, unknown>;
+
+        if (shellIntegrationInspect.workspaceFolderValue !== undefined) {
+            shellIntegrationEnabled = shellIntegrationInspect.workspaceFolderValue;
+        } else if (shellIntegrationInspect.workspaceValue !== undefined) {
+            shellIntegrationEnabled = shellIntegrationInspect.workspaceValue;
+        } else if ('globalRemoteValue' in shellIntegrationInspect && inspectValue.globalRemoteValue !== undefined) {
+            shellIntegrationEnabled = inspectValue.globalRemoteValue as boolean;
+        } else if ('globalLocalValue' in shellIntegrationInspect && inspectValue.globalLocalValue !== undefined) {
+            shellIntegrationEnabled = inspectValue.globalLocalValue as boolean;
+        } else if (shellIntegrationInspect.globalValue !== undefined) {
+            shellIntegrationEnabled = shellIntegrationInspect.globalValue;
+        } else if (shellIntegrationInspect.defaultValue !== undefined) {
+            shellIntegrationEnabled = shellIntegrationInspect.defaultValue;
+        }
+    }
+
+    await persistentState.set(SHELL_INTEGRATION_STATE_KEY, shellIntegrationEnabled);
+    return shellIntegrationEnabled;
+}

src/features/terminal/shells/fish/fishStartup.ts

@@ -6,7 +6,7 @@ import which from 'which';
 import { traceError, traceInfo, traceVerbose } from '../../../../common/logging';
 import { ShellConstants } from '../../../common/shellConstants';
 import { hasStartupCode, insertStartupCode, removeStartupCode } from '../common/editUtils';
-import { isWsl, shellIntegrationForActiveTerminal } from '../common/shellUtils';
+import { getShellIntegrationEnabledCache, isWsl, shellIntegrationForActiveTerminal } from '../common/shellUtils';
 import { ShellScriptEditState, ShellSetupState, ShellStartupScriptProvider } from '../startupProvider';
 import { FISH_ENV_KEY, FISH_OLD_ENV_KEY, FISH_SCRIPT_VERSION } from './fishConstants';
 
@@ -58,7 +58,8 @@ async function isStartupSetup(profilePath: string, key: string): Promise<boolean
 
 async function setupStartup(profilePath: string, key: string): Promise<boolean> {
     try {
-        if (shellIntegrationForActiveTerminal('fish', profilePath) && !isWsl()) {
+        const shellIntegrationEnabled = await getShellIntegrationEnabledCache();
+        if ((shellIntegrationEnabled || (await shellIntegrationForActiveTerminal('fish', profilePath))) && !isWsl()) {
             removeFishStartup(profilePath, key);
             return true;
         }

src/features/terminal/shells/pwsh/pwshStartup.ts

@@ -13,6 +13,7 @@ import { ShellConstants } from '../../../common/shellConstants';
 import { hasStartupCode, insertStartupCode, removeStartupCode } from '../common/editUtils';
 import {
     extractProfilePath,
+    getShellIntegrationEnabledCache,
     isWsl,
     PROFILE_TAG_END,
     PROFILE_TAG_START,
@@ -58,6 +59,27 @@ async function isPowerShellInstalled(shell: string): Promise<boolean> {
     }
 }
 
+/**
+ * Detects the major version of PowerShell by executing a version query command.
+ * This helps with debugging activation issues since PowerShell 5.x and 7+ have different behaviors.
+ * @param shell The PowerShell executable name ('powershell' for Windows PowerShell or 'pwsh' for PowerShell Core/7+)
+ * @returns Promise resolving to the major version number as a string, or undefined if detection fails
+ */
+async function getPowerShellVersion(shell: 'powershell' | 'pwsh'): Promise<string | undefined> {
+    try {
+        const command = `${shell} -c '\$PSVersionTable.PSVersion.Major'`;
+        const versionOutput = await runCommand(command);
+        if (versionOutput && !isNaN(Number(versionOutput))) {
+            return versionOutput;
+        }
+        traceVerbose(`Failed to parse PowerShell version from output: ${versionOutput}`);
+        return undefined;
+    } catch (err) {
+        traceVerbose(`Failed to get PowerShell version for ${shell}`, err);
+        return undefined;
+    }
+}
+
 async function getProfileForShell(shell: 'powershell' | 'pwsh'): Promise<string> {
     const cachedPath = getProfilePathCache(shell);
     if (cachedPath) {
@@ -125,7 +147,8 @@ function getActivationContent(): string {
         '        try {',
         `            Invoke-Expression $env:${POWERSHELL_ENV_KEY}`,
         '        } catch {',
-        `            Write-Error "Failed to activate Python environment: $_" -ErrorAction Continue`,
+        `            $psVersion = $PSVersionTable.PSVersion.Major`,
+        `            Write-Error "Failed to activate Python environment (PowerShell $psVersion): $_" -ErrorAction Continue`,
         '        }',
         '    }',
         '}',
@@ -146,7 +169,9 @@ async function isPowerShellStartupSetup(shell: string, profile: string): Promise
 }
 
 async function setupPowerShellStartup(shell: string, profile: string): Promise<boolean> {
-    if (shellIntegrationForActiveTerminal(shell, profile) && !isWsl()) {
+    const shellIntegrationEnabled = await getShellIntegrationEnabledCache();
+
+    if ((shellIntegrationEnabled || (await shellIntegrationForActiveTerminal(shell, profile))) && !isWsl()) {
         removePowerShellStartup(shell, profile, POWERSHELL_OLD_ENV_KEY);
         removePowerShellStartup(shell, profile, POWERSHELL_ENV_KEY);
         return true;
@@ -220,6 +245,12 @@ export class PwshStartupProvider implements ShellStartupScriptProvider {
                     results.set(shell, this._isPs5Installed);
                 } else {
                     const isInstalled = await isPowerShellInstalled(shell);
+                    if (isInstalled) {
+                        // Log PowerShell version for debugging activation issues
+                        const version = await getPowerShellVersion(shell);
+                        const versionText = version ? ` (version ${version})` : ' (version unknown)';
+                        traceInfo(`SHELL: ${shell} is installed${versionText}`);
+                    }
                     if (shell === 'pwsh') {
                         this._isPwshInstalled = isInstalled;
                     } else {