fix: bridge Python environment selection to content creator commands (#2763)

## Bridge Python environment selection to content creator commands

### Problem

Content creator commands (`ansible-creator`, `ade`, etc.) were not
respecting the Python environment selected in VS Code. When users
selected a virtual environment containing these tools, the extension
would still attempt to execute them using system Python, resulting in
"command not found" errors even when the tools were correctly installed
in the selected venv.

This affected:
- Collection/Project/Role/Devfile/Devcontainer creation panels
- Execution Environment panel
- Ansible Vault operations
- All commands executed via `withInterpreter()`

### Root Cause

The `withInterpreter()` helper was a legacy synchronous function that
only set `ANSIBLE_FORCE_COLOR` and `PYTHONBREAKPOINT` environment
variables. It did not:
1. Resolve the active Python environment
2. Add the venv's `bin/` directory to `PATH`
3. Set `VIRTUAL_ENV` for tools that check it

Additionally, `PythonEnvironmentService.getEnvironment()` would return
system Python when no workspace scope was provided, even when a
workspace-specific venv was selected.

### Solution

#### 1. Enhanced `withInterpreter()` to bridge Python environment

- Made function async to support environment resolution
- Integrated `PythonEnvironmentService` to resolve interpreter path
- Added venv `bin/` directory to `PATH` before command execution
- Set `VIRTUAL_ENV` environment variable for compatibility

#### 2. Workspace scope defaulting

Added intelligent scope resolution in
`PythonEnvironmentService.getEnvironment()`:
- Defaults to first workspace folder when no scope provided
- Ensures workspace-specific Python environments are used instead of
system Python
- Maintains explicit scope behavior when caller provides one

#### 3. Configuration middleware improvements

- Added `PythonEnvironmentService.resolveInterpreterPath()` to
centralize path resolution
- Expanded tilde (`~`) and `${workspaceFolder}` in user-configured
interpreter paths
- Added error handling for configuration fetch and environment
resolution failures
- Send expanded paths to language server to avoid server-side expansion
issues

#### 4. Execution Environment webview parity

- Added requirements checking to Execution Environment panel (previously
missing)
- Added `RequirementsBanner` component to show version check results
- Aligned behavior with other content creator panels

### Changes

**Core Infrastructure:**
- `src/features/utils/commandRunner.ts` - Made `withInterpreter()` async
with venv PATH support
- `src/services/PythonEnvironmentService.ts` - Added scope defaulting
and `resolveInterpreterPath()` method

**Updated Callers (now await async `withInterpreter()`):**
- `src/extension.ts` - ansible-creator and ansible-dev-tools
installation commands
- `src/features/contentCreator/utils.ts` - `getBinDetail()` for version
checks
- `src/features/lightspeed/vue/views/ansibleCreatorUtils.ts` - Role,
plugin, collection, project creation
- `src/features/lightspeed/vue/views/webviewMessageHandlers.ts` -
Execution environment init
- `src/features/utils/buildExecutionEnvironment.ts` - EE build command
- `src/features/vault.ts` - All ansible-vault operations

**Configuration Middleware:**
- `src/extension.ts` - `makeConfigurationMiddleware()` now expands user
paths and handles errors gracefully

**UI:**
- `src/features/contentCreator/vue/views/createExecutionEnvPanel.ts` -
Added requirements check message handler
- `webviews/CreateExecutionEnvApp.vue` - Added `RequirementsBanner` and
requirements state

**Tests:**
- `test/unit/utils/commandRunner.test.ts` - New comprehensive unit tests
(10 tests)
- `test/unit/services/PythonEnvironmentService.test.ts` - Added scope
resolution tests (6 new tests)
- `test/unit/configurationMiddleware.test.ts` - Added error handling and
path expansion tests (3 new tests)

### Testing

**Unit Tests:** 56 tests (54 passing, 2 skipped)
- `commandRunner.test.ts` - Validates PATH manipulation, environment
variable setting, scope handling
- `PythonEnvironmentService.test.ts` - Tests scope resolution for
single/multi-workspace scenarios
- `configurationMiddleware.test.ts` - Validates path expansion and error
handling

**Integration Tests:**
- `utilities.test.ts` - Validates real command execution through
`getBinDetail()`

### Migration Notes

The changes are backward compatible:
- `withInterpreter()` is now async but maintains the same return
signature
- All callers updated to use `await`
- No configuration changes required from users
- Workspace scope defaulting is transparent

### Limitations

- Multi-workspace setups default to first workspace folder when no scope
provided (RFE: add workspace picker for ambiguous cases)
- Debug logging added temporarily to aid troubleshooting (can be removed
after stabilization)

## Identified Regression

In #2757, the resources for devfile and devcontainer were identified as
build artifacts, when they need to be packaged into the final .vsix. The
fixes for this were incorporated into this change due to urgency.

Author: alisonlhart

.gitignore

@@ -26,6 +26,8 @@ CHANGELOG.html
 docs/als/settings.md
 examples/.vscode/
 packages/ansible-language-server/test/fixtures/diagnostics/invalid_yaml.yml
+resources/contentCreator/createDevcontainer/.devcontainer
+resources/contentCreator/createDevfile/devfile-template.txt
 test/testFixtures/.vscode/settings.json
 test/testFixtures/diagnostics/yaml/invalid_yaml.yml
 test/unit/lightspeed/utils/samples/collections/ansible_collections/community/broken_MANIFEST/MANIFEST.json

Taskfile.base.yml

@@ -30,8 +30,8 @@ tasks:
     generates:
       - "{{ .VIRTUAL_ENV }}/pyvenv.cfg"
       - "{{ .VIRTUAL_ENV }}/CACHEDIR.TAG"
-      - out/resources/contentCreator/createDevfile/devfile-template.txt
-      - out/resources/contentCreator/createDevcontainer/.devcontainer
+      - resources/contentCreator/createDevfile/devfile-template.txt
+      - resources/contentCreator/createDevcontainer/.devcontainer
     dir: "{{ .TASKFILE_DIR }}"
     sources:
       - pyproject.toml

src/extension.ts

@@ -596,7 +596,7 @@ export async function activate(context: ExtensionContext): Promise<void> {
         const pythonInterpreter = extSettings.settings.interpreterPath;
 
         // specify the current python interpreter path in the pip installation
-        const { command, env } = withInterpreter(
+        const { command, env } = await withInterpreter(
           extSettings.settings,
           `${pythonInterpreter} -m pip install ansible-creator`,
           "--no-input",
@@ -1032,7 +1032,7 @@ export async function activate(context: ExtensionContext): Promise<void> {
         const pythonInterpreter = extSettings.settings.interpreterPath;
 
         // specify the current python interpreter path in the pip installation
-        const { command, env } = withInterpreter(
+        const { command, env } = await withInterpreter(
           extSettings.settings,
           `${pythonInterpreter} -m pip install ansible-dev-tools`,
           "--no-input",
@@ -1447,7 +1447,16 @@ export function makeConfigurationMiddleware(
     ) => HandlerResult<LSPAny[], void>,
   ): HandlerResult<LSPAny[], void> => {
     return (async (): Promise<LSPAny[]> => {
-      const originalResult = await next(params, token);
+      let originalResult: LSPAny[] | LSPAny;
+      try {
+        originalResult = await next(params, token);
+      } catch (error) {
+        outputChannel.appendLine(
+          `[Ansible] Configuration middleware error: ${error}`,
+        );
+        return [] as unknown as LSPAny[];
+      }
+
       if (!Array.isArray(originalResult))
         return originalResult as unknown as LSPAny[];
 
@@ -1467,18 +1476,49 @@ export function makeConfigurationMiddleware(
         const rawInterpreterPath = pythonConfig?.interpreterPath;
 
         if (typeof rawInterpreterPath === "string" && rawInterpreterPath) {
-          // User has explicit config, log only on change
+          // User has explicit config - use centralized resolver to expand ~ and ${workspaceFolder}
+          const scope = scopeUri ? vscode.Uri.parse(scopeUri) : undefined;
+          const resolvedUserPath =
+            await pythonEnvService.resolveInterpreterPath(
+              rawInterpreterPath,
+              scope,
+            );
+
+          // Log only on change (compare raw path for deduplication)
           if (lastLoggedUserByScope.get(scopeUri) !== rawInterpreterPath) {
             outputChannel.appendLine(
-              `[Ansible] Using user-configured interpreterPath: ${rawInterpreterPath}`,
+              `[Ansible] Using user-configured interpreterPath: ${rawInterpreterPath}${resolvedUserPath !== rawInterpreterPath ? ` (resolved: ${resolvedUserPath})` : ""}`,
             );
             lastLoggedUserByScope.set(scopeUri, rawInterpreterPath);
           }
+
+          // Inject the expanded path if expansion succeeded
+          if (resolvedUserPath && resolvedUserPath !== rawInterpreterPath) {
+            result[i] = {
+              ...config,
+              python: {
+                ...pythonConfig,
+                interpreterPath: resolvedUserPath,
+              },
+            };
+          }
           continue;
         }
 
         const scope = scopeUri ? vscode.Uri.parse(scopeUri) : undefined;
-        const resolvedPath = await pythonEnvService.getExecutablePath(scope);
+        let resolvedPath: string | undefined;
+        try {
+          resolvedPath = await pythonEnvService.getExecutablePath(scope);
+        } catch (error) {
+          // Treat resolution failure as "no path" - log once and leave config unchanged
+          if (lastLoggedResolvedByScope.get(scopeUri) !== "") {
+            outputChannel.appendLine(
+              `[Ansible] Failed to resolve Python environment: ${error}`,
+            );
+            lastLoggedResolvedByScope.set(scopeUri, "");
+          }
+          continue;
+        }
 
         if (resolvedPath) {
           // Log only when path actually changes

src/features/contentCreator/utils.ts

@@ -9,7 +9,11 @@ export async function getBinDetail(cmd: string, arg: string) {
   const extSettings = new SettingsManager();
   await extSettings.initialize();
 
-  const { command, env } = withInterpreter(extSettings.settings, cmd, arg);
+  const { command, env } = await withInterpreter(
+    extSettings.settings,
+    cmd,
+    arg,
+  );
 
   try {
     const result = cp.execSync(command, {

src/features/contentCreator/vue/views/createExecutionEnvPanel.ts

@@ -5,6 +5,7 @@ import {
   disposePanelResources,
   createOrRevealPanel,
 } from "@src/features/contentCreator/vue/views/panelUtils";
+import { checkContentCreatorRequirements } from "@src/features/contentCreator/utils";
 
 export class MainPanel {
   public static currentPanel: MainPanel | undefined;
@@ -20,6 +21,20 @@ export class MainPanel {
       this._disposables,
       () => this.dispose(),
     );
+
+    this._panel.webview.onDidReceiveMessage(
+      async (msg) => {
+        if (msg && msg.type === "request-requirements-status") {
+          const status = await checkContentCreatorRequirements();
+          this._panel.webview.postMessage({
+            type: "requirements-status",
+            ...status,
+          });
+        }
+      },
+      null,
+      this._disposables,
+    );
   }
 
   public static render(context: ExtensionContext) {

src/features/lightspeed/vue/views/ansibleCreatorUtils.ts

@@ -91,7 +91,7 @@ export class AnsibleCreatorOperations {
     const extSettings = new SettingsManager();
     await extSettings.initialize();
 
-    const { command, env } = withInterpreter(
+    const { command, env } = await withInterpreter(
       extSettings.settings,
       ansibleCreatorAddCommand,
       "",
@@ -190,7 +190,7 @@ export class AnsibleCreatorOperations {
     const extSettings = new SettingsManager();
     await extSettings.initialize();
 
-    const { command, env } = withInterpreter(
+    const { command, env } = await withInterpreter(
       extSettings.settings,
       ansibleCreatorAddCommand,
       "",
@@ -362,7 +362,7 @@ export class AnsibleCreatorOperations {
     const extSettings = new SettingsManager();
     await extSettings.initialize();
 
-    const { command, env } = withInterpreter(
+    const { command, env } = await withInterpreter(
       extSettings.settings,
       ansibleCreatorInitCommand,
       "",
@@ -415,7 +415,7 @@ export class AnsibleCreatorOperations {
 
       if (exceedADEImVersion) {
         adeCommand += " --im=cfg";
-        const { command, env } = withInterpreter(
+        const { command, env } = await withInterpreter(
           extSettings.settings,
           adeCommand,
           "",

src/features/lightspeed/vue/views/webviewMessageHandlers.ts

@@ -742,10 +742,8 @@ export class WebviewMessageHandlers {
 
       const templateSourcePath = vscode.Uri.joinPath(
         extensionUri,
-        "out/resources/contentCreator/createDevcontainer/.devcontainer",
-      )
-        .toString()
-        .replace("file://", "");
+        "resources/contentCreator/createDevcontainer/.devcontainer",
+      ).fsPath;
 
       await this.scaffoldDevcontainerStructure(
         templateSourcePath,
@@ -872,7 +870,7 @@ export class WebviewMessageHandlers {
   ) {
     let devfile: string;
     const relativeTemplatePath =
-      "out/resources/contentCreator/createDevfile/devfile-template.txt";
+      "resources/contentCreator/createDevfile/devfile-template.txt";
 
     const expandedDestUrl = expandPath(destinationUrl);
 
@@ -882,9 +880,7 @@ export class WebviewMessageHandlers {
     const absoluteTemplatePath = vscode.Uri.joinPath(
       extensionUri,
       relativeTemplatePath,
-    )
-      .toString()
-      .replace("file://", "");
+    ).fsPath;
 
     try {
       const dirPath = path.dirname(expandedDestUrl);
@@ -1104,7 +1100,7 @@ export class WebviewMessageHandlers {
         const extSettings = new SettingsManager();
         await extSettings.initialize();
 
-        const { command, env } = withInterpreter(
+        const { command, env } = await withInterpreter(
           extSettings.settings,
           initEEProjectCommand,
           "",

src/features/utils/buildExecutionEnvironment.ts

@@ -43,7 +43,7 @@ export function rightClickEEBuildCommand(commandId: string): vscode.Disposable {
       const extSettings = new SettingsManager();
       await extSettings.initialize();
 
-      const { command, env } = withInterpreter(
+      const { command, env } = await withInterpreter(
         extSettings.settings,
         builderCommand,
         "",

src/features/utils/commandRunner.ts

@@ -1,33 +1,64 @@
-/* stdlib */
-
 /* local */
+import * as path from "path";
+import * as vscode from "vscode";
 import type { ExtensionSettings } from "@src/interfaces/extensionSettings";
+import { PythonEnvironmentService } from "@src/services/PythonEnvironmentService";
 
 /**
- * A helper method to build a command with appropriate environment variables.
+ * Build a command with the active Python environment's bin directory in PATH.
+ * Uses Python environment resolution with user config fallback.
+ * This ensures commands like ansible-creator run from the correct venv.
  *
- * NOTE: This function is maintained for backward compatibility.
- * For terminal-based execution, prefer using TerminalService which handles
+ * NOTE: For terminal-based execution, prefer using TerminalService which handles
  * Python environment activation automatically via the Python extension.
  *
  * @param settings - The extension setting.
  * @param runExecutable - The name of the executable to run.
  * @param cmdArgs - The arguments to the executable.
- * @returns The complete command to be executed with environment.
+ * @param scope - Optional workspace scope for environment resolution.
+ * @returns Promise resolving to the command and environment with venv PATH.
  */
-export function withInterpreter(
+export async function withInterpreter(
   settings: ExtensionSettings,
   runExecutable: string,
   cmdArgs: string,
-): { command: string; env: NodeJS.ProcessEnv } {
+  scope?: import("vscode").Uri,
+): Promise<{ command: string; env: NodeJS.ProcessEnv }> {
+  // Build command string
   const command = `${runExecutable} ${cmdArgs}`;
 
-  const newEnv = Object.assign({}, process.env, {
+  // Start with base environment and Ansible-specific vars
+  const env = Object.assign({}, process.env, {
     ANSIBLE_FORCE_COLOR: "0", // ensure output is parsable (no ANSI)
-    PYTHONBREAKPOINT: "0", // We want to be sure that python debugger is never
-    // triggered, even if we mistakenly left a breakpoint() there while
-    // debugging ansible-lint, or another tool we call.
+    PYTHONBREAKPOINT: "0", // prevent debugger from being triggered
   });
 
-  return { command: command, env: newEnv } as const;
+  // Resolve Python environment and add venv bin to PATH
+  const pythonEnvService = PythonEnvironmentService.getInstance();
+
+  // Get interpreter path (respects user config, then Python extension)
+  const execPath = await pythonEnvService.resolveInterpreterPath(
+    settings.interpreterPath,
+    scope,
+  );
+
+  if (execPath) {
+    // Add venv bin directory to PATH (like TerminalService does)
+    const binDir = path.dirname(execPath);
+    const existingPath = env.PATH ?? process.env.PATH ?? "";
+    env.PATH = `${binDir}${path.delimiter}${existingPath}`;
+
+    // Set VIRTUAL_ENV for tools that check it (defensive pattern from TerminalService)
+    const environment = await pythonEnvService.getEnvironment(scope);
+    if (environment?.environmentPath) {
+      const envPath = environment.environmentPath;
+      if (envPath instanceof vscode.Uri) {
+        env.VIRTUAL_ENV = envPath.fsPath;
+      } else if (typeof envPath === "string") {
+        env.VIRTUAL_ENV = envPath;
+      }
+    }
+  }
+
+  return { command, env };
 }

src/features/vault.ts

@@ -50,11 +50,15 @@ function displayInvalidConfigError(): void {
 export class Vault {
   constructor(private extSettings: SettingsManager) {}
 
-  private ansibleVaultCmd(args: string): {
+  private async ansibleVaultCmd(args: string): Promise<{
     command: string;
     env: NodeJS.ProcessEnv;
-  } {
-    return withInterpreter(this.extSettings.settings, "ansible-vault", args);
+  }> {
+    return await withInterpreter(
+      this.extSettings.settings,
+      "ansible-vault",
+      args,
+    );
   }
 
   async toggleEncrypt(): Promise<void> {
@@ -272,7 +276,7 @@ export class Vault {
     });
   }
 
-  private encryptText(
+  private async encryptText(
     text: string,
     rootPath: string | undefined,
     vaultId: string | undefined,
@@ -281,20 +285,20 @@ export class Vault {
     if (vaultId) {
       args += ` --encrypt-vault-id ${vaultId}`;
     }
-    const { command: cmd, env } = this.ansibleVaultCmd(args);
+    const { command: cmd, env } = await this.ansibleVaultCmd(args);
     return this.pipeTextThroughCmd(text, rootPath, cmd, env);
   }
 
-  private decryptText(
+  private async decryptText(
     text: string,
     rootPath: string | undefined,
   ): Promise<string> {
     const args = "decrypt";
-    const { command: cmd, env } = this.ansibleVaultCmd(args);
+    const { command: cmd, env } = await this.ansibleVaultCmd(args);
     return this.pipeTextThroughCmd(text, rootPath, cmd, env);
   }
 
-  private encryptFile(
+  private async encryptFile(
     f: string,
     rootPath: string | undefined,
     vaultId: string | undefined,
@@ -305,15 +309,15 @@ export class Vault {
       "encrypt " +
       (vaultId ? `--encrypt-vault-id="${vaultId}" ` : "") +
       `"${f}"`;
-    const { command: cmd, env } = this.ansibleVaultCmd(args);
+    const { command: cmd, env } = await this.ansibleVaultCmd(args);
 
     return execCwd(cmd, rootPath, env);
   }
 
-  private decryptFile = (f: string, rootPath: string | undefined) => {
+  private decryptFile = async (f: string, rootPath: string | undefined) => {
     console.log(`Decrypt file: ${f}`);
     const args = `decrypt "${f}"`;
-    const { command: cmd, env } = this.ansibleVaultCmd(args);
+    const { command: cmd, env } = await this.ansibleVaultCmd(args);
 
     return execCwd(cmd, rootPath, env);
   };