Prompt to automatically install missing toolchain (#1855)

If a .swift-version exists in a project that specifies a toolchain the
user doesn't have installed, prompt them to install it on extension
launch.

If they cancel the dialog, fall back to using whatever toolchain is
already installed, basically ignoring the .swift-version for this
activation or until the .swift-version is changed again.

Issue: #1852

Author: plemarquand

src/commands/installSwiftlyToolchain.ts

@@ -15,6 +15,7 @@ import * as vscode from "vscode";
 import { QuickPickItem } from "vscode";
 
 import { WorkspaceContext } from "../WorkspaceContext";
+import { SwiftLogger } from "../logging/SwiftLogger";
 import {
     Swiftly,
     SwiftlyProgressData,
@@ -29,11 +30,26 @@ interface SwiftlyToolchainItem extends QuickPickItem {
 }
 
 async function downloadAndInstallToolchain(selected: SwiftlyToolchainItem, ctx: WorkspaceContext) {
+    return await installSwiftlyToolchainVersion(selected.toolchain.version.name, ctx.logger, true);
+}
+
+/**
+ * Installs a Swiftly toolchain by version string
+ * @param version The toolchain version to install
+ * @param logger Optional logger for error reporting
+ * @param showReloadNotification Whether to show reload notification after installation
+ * @returns Promise<boolean> true if installation succeeded, false otherwise
+ */
+export async function installSwiftlyToolchainVersion(
+    version: string,
+    logger?: SwiftLogger,
+    showReloadNotification: boolean = true
+): Promise<boolean> {
     try {
         await vscode.window.withProgress(
             {
                 location: vscode.ProgressLocation.Notification,
-                title: `Installing Swift ${selected.toolchain.version.name}`,
+                title: `Installing Swift ${version}`,
                 cancellable: false,
             },
             async progress => {
@@ -42,7 +58,7 @@ async function downloadAndInstallToolchain(selected: SwiftlyToolchainItem, ctx:
                 let lastProgress = 0;
 
                 await Swiftly.installToolchain(
-                    selected.toolchain.version.name,
+                    version,
                     (progressData: SwiftlyProgressData) => {
                         if (
                             progressData.step?.percent !== undefined &&
@@ -58,7 +74,7 @@ async function downloadAndInstallToolchain(selected: SwiftlyToolchainItem, ctx:
                             lastProgress = progressData.step.percent;
                         }
                     },
-                    ctx.logger
+                    logger
                 );
 
                 progress.report({
@@ -67,14 +83,17 @@ async function downloadAndInstallToolchain(selected: SwiftlyToolchainItem, ctx:
                 });
             }
         );
-        void showReloadExtensionNotification(
-            `Swift ${selected.toolchain.version.name} has been installed and activated. Visual Studio Code needs to be reloaded.`
-        );
+
+        if (showReloadNotification) {
+            void showReloadExtensionNotification(
+                `Swift ${version} has been installed and activated. Visual Studio Code needs to be reloaded.`
+            );
+        }
+        return true;
     } catch (error) {
-        ctx.logger?.error(`Failed to install Swift ${selected.toolchain.version.name}: ${error}`);
-        void vscode.window.showErrorMessage(
-            `Failed to install Swift ${selected.toolchain.version.name}: ${error}`
-        );
+        logger?.error(`Failed to install Swift ${version}: ${error}`);
+        void vscode.window.showErrorMessage(`Failed to install Swift ${version}: ${error}`);
+        return false;
     }
 }
 

src/toolchain/swiftly.ts

@@ -20,7 +20,10 @@ import * as Stream from "stream";
 import * as vscode from "vscode";
 import { z } from "zod/v4/mini";
 
+// Import the reusable installation function
+import { installSwiftlyToolchainVersion } from "../commands/installSwiftlyToolchain";
 import { SwiftLogger } from "../logging/SwiftLogger";
+import { showMissingToolchainDialog } from "../ui/ToolchainSelection";
 import { findBinaryPath } from "../utilities/shell";
 import { ExecFileError, execFile, execFileStreamOutput } from "../utilities/utilities";
 import { Version } from "../utilities/version";
@@ -127,6 +130,56 @@ export interface PostInstallValidationResult {
     invalidCommands?: string[];
 }
 
+export interface MissingToolchainError {
+    version: string;
+    originalError: string;
+}
+
+/**
+ * Parses Swiftly error message to detect missing toolchain scenarios
+ * @param stderr The stderr output from swiftly command
+ * @returns MissingToolchainError if this is a missing toolchain error, undefined otherwise
+ */
+export function parseSwiftlyMissingToolchainError(
+    stderr: string
+): MissingToolchainError | undefined {
+    // Parse error message like: "uses toolchain version 6.1.2, but it doesn't match any of the installed toolchains"
+    const versionMatch = stderr.match(/uses toolchain version ([0-9.]+(?:-[a-zA-Z0-9-]+)*)/);
+    if (versionMatch && stderr.includes("doesn't match any of the installed toolchains")) {
+        return {
+            version: versionMatch[1],
+            originalError: stderr,
+        };
+    }
+    return undefined;
+}
+
+/**
+ * Attempts to automatically install a missing Swiftly toolchain with user consent
+ * @param version The toolchain version to install
+ * @param logger Optional logger for error reporting
+ * @param folder Optional folder context
+ * @returns Promise<boolean> true if toolchain was successfully installed, false otherwise
+ */
+export async function handleMissingSwiftlyToolchain(
+    version: string,
+    logger?: SwiftLogger,
+    folder?: vscode.Uri
+): Promise<boolean> {
+    logger?.info(`Attempting to handle missing toolchain: ${version}`);
+
+    // Ask user for permission
+    const userConsent = await showMissingToolchainDialog(version, folder);
+    if (!userConsent) {
+        logger?.info(`User declined to install missing toolchain: ${version}`);
+        return false;
+    }
+
+    // Use the existing installation function without showing reload notification
+    // (since we want to continue the current operation)
+    return await installSwiftlyToolchainVersion(version, logger, false);
+}
+
 export class Swiftly {
     /**
      * Finds the version of Swiftly installed on the system.
@@ -287,7 +340,39 @@ export class Swiftly {
                 } catch (err: unknown) {
                     logger?.error(`Failed to retrieve Swiftly installations: ${err}`);
                     const error = err as ExecFileError;
-                    // Its possible the toolchain in .swift-version is misconfigured or doesn't exist.
+
+                    // Check if this is a missing toolchain error
+                    const missingToolchainError = parseSwiftlyMissingToolchainError(error.stderr);
+                    if (missingToolchainError) {
+                        // Attempt automatic installation
+                        const installed = await handleMissingSwiftlyToolchain(
+                            missingToolchainError.version,
+                            logger,
+                            cwd
+                        );
+
+                        if (installed) {
+                            // Retry toolchain location after successful installation
+                            try {
+                                const retryInUse = await Swiftly.inUseLocation("swiftly", cwd);
+                                if (retryInUse.length > 0) {
+                                    return path.join(retryInUse, "usr");
+                                }
+                            } catch (retryError) {
+                                logger?.error(
+                                    `Failed to use toolchain after installation: ${retryError}`
+                                );
+                            }
+                        } else {
+                            // User declined installation - gracefully fall back to global toolchain
+                            logger?.info(
+                                `Falling back to global toolchain after user declined installation of missing toolchain: ${missingToolchainError.version}`
+                            );
+                            return undefined;
+                        }
+                    }
+
+                    // Fall back to original error handling for non-missing-toolchain errors
                     void vscode.window.showErrorMessage(
                         `Failed to load toolchain from Swiftly: ${error.stderr}`
                     );

src/ui/ToolchainSelection.ts

@@ -100,6 +100,25 @@ export async function showToolchainError(folder?: vscode.Uri): Promise<boolean>
     return false;
 }
 
+/**
+ * Shows a dialog asking user permission to install a missing Swiftly toolchain
+ * @param version The toolchain version to install
+ * @param folder Optional folder context for the error
+ * @returns Promise<boolean> true if user agrees to install, false otherwise
+ */
+export async function showMissingToolchainDialog(
+    version: string,
+    folder?: vscode.Uri
+): Promise<boolean> {
+    const folderName = folder ? `${FolderContext.uriName(folder)}: ` : "";
+    const message =
+        `${folderName}Swift version ${version} is required but not installed. ` +
+        `Would you like to automatically install it using Swiftly?`;
+
+    const choice = await vscode.window.showWarningMessage(message, "Install Toolchain", "Cancel");
+    return choice === "Install Toolchain";
+}
+
 export async function selectToolchain() {
     await vscode.commands.executeCommand(Commands.SELECT_TOOLCHAIN);
 }

test/unit-tests/toolchain/swiftly.test.ts

@@ -19,7 +19,11 @@ import { match } from "sinon";
 import * as vscode from "vscode";
 
 import * as SwiftOutputChannelModule from "@src/logging/SwiftOutputChannel";
-import { Swiftly } from "@src/toolchain/swiftly";
+import {
+    Swiftly,
+    handleMissingSwiftlyToolchain,
+    parseSwiftlyMissingToolchainError,
+} from "@src/toolchain/swiftly";
 import * as utilities from "@src/utilities/utilities";
 
 import { mockGlobalModule, mockGlobalObject, mockGlobalValue } from "../../MockUtils";
@@ -1031,4 +1035,72 @@ apt-get -y install libncurses5-dev
             expect(mockUtilities.execFile).to.not.have.been.calledWith("pkexec", match.array);
         });
     });
+
+    suite("Missing Toolchain Handling", () => {
+        test("parseSwiftlyMissingToolchainError parses version correctly", () => {
+            const stderr =
+                "The swift version file uses toolchain version 6.1.2, but it doesn't match any of the installed toolchains. You can install the toolchain with `swiftly install`.";
+            const result = parseSwiftlyMissingToolchainError(stderr);
+            expect(result?.version).to.equal("6.1.2");
+            expect(result?.originalError).to.equal(stderr);
+        });
+
+        test("parseSwiftlyMissingToolchainError returns undefined for other errors", () => {
+            const stderr = "Some other error message";
+            const result = parseSwiftlyMissingToolchainError(stderr);
+            expect(result).to.be.undefined;
+        });
+
+        test("parseSwiftlyMissingToolchainError handles snapshot versions", () => {
+            const stderr =
+                "uses toolchain version 6.1-snapshot-2024-12-01, but it doesn't match any of the installed toolchains";
+            const result = parseSwiftlyMissingToolchainError(stderr);
+            expect(result?.version).to.equal("6.1-snapshot-2024-12-01");
+        });
+
+        test("parseSwiftlyMissingToolchainError handles versions with hyphens", () => {
+            const stderr =
+                "uses toolchain version 6.0-dev, but it doesn't match any of the installed toolchains";
+            const result = parseSwiftlyMissingToolchainError(stderr);
+            expect(result?.version).to.equal("6.0-dev");
+        });
+    });
+
+    suite("handleMissingSwiftlyToolchain", () => {
+        const mockWindow = mockGlobalObject(vscode, "window");
+        const mockedUtilities = mockGlobalModule(utilities);
+        const mockSwiftlyInstallToolchain = mockGlobalValue(Swiftly, "installToolchain");
+
+        test("handleMissingSwiftlyToolchain returns false when user declines installation", async () => {
+            mockWindow.showWarningMessage.resolves(undefined); // User cancels/declines
+            const result = await handleMissingSwiftlyToolchain("6.1.2");
+            expect(result).to.be.false;
+        });
+
+        test("handleMissingSwiftlyToolchain returns true when user accepts and installation succeeds", async () => {
+            // User accepts the installation
+            mockWindow.showWarningMessage.resolves("Install Toolchain" as any);
+
+            // Mock successful installation with progress
+            mockWindow.withProgress.callsFake(async (_options, task) => {
+                const mockProgress = { report: () => {} };
+                const mockToken = {
+                    isCancellationRequested: false,
+                    onCancellationRequested: () => ({ dispose: () => {} }),
+                };
+                await task(mockProgress, mockToken);
+                return true;
+            });
+
+            mockSwiftlyInstallToolchain.setValue(() => Promise.resolve(void 0));
+
+            // Mock the installSwiftlyToolchainVersion to succeed
+            mockedUtilities.execFile
+                .withArgs("swiftly", match.any)
+                .resolves({ stdout: "", stderr: "" });
+
+            const result = await handleMissingSwiftlyToolchain("6.1.2");
+            expect(result).to.be.true;
+        });
+    });
 });