feat(lambda): add installation of LocalStack extension to AppBuilder Walkthrough

Update AppBuilder Walkthrough wording and add LocalStack VS Code
extension

Author: valerena

packages/core/package.nls.json

@@ -478,7 +478,7 @@
     "AWS.toolkit.lambda.walkthrough.title": "Get started building your application",
     "AWS.toolkit.lambda.walkthrough.description": "Your quick guide to build an application visually, iterate locally, and deploy to the cloud!",
     "AWS.toolkit.lambda.walkthrough.toolInstall.title": "Complete installation",
-    "AWS.toolkit.lambda.walkthrough.toolInstall.description": "The AWS Command Line Interface (AWS CLI) is an open source tool that enables you to interact with AWS services using commands in your command-line shell. It is required to create and interact with AWS resources. \n\n[Install AWS CLI](command:aws.toolkit.installAWSCLI)\n\n Use the Serverless Application Model (SAM) CLI to locally build, invoke, and deploy your functions. Version 1.98+ is required. \n\n[Install SAM CLI](command:aws.toolkit.installSAMCLI)\n\n Use Docker to locally emulate a Lambda environment. Docker is optional. However, if you want to invoke locally, Docker is required so Lambda can locally emulate the execution environment. \n\n[Install Docker (optional)](command:aws.toolkit.installDocker)",
+    "AWS.toolkit.lambda.walkthrough.toolInstall.description": "Manage your AWS services and resources with the AWS Command Line Interface (AWS CLI). \n\n[Install AWS CLI](command:aws.toolkit.installAWSCLI)\n\nBuild locally, invoke, and deploy your functions with the Serverless Application Model (SAM) CLI. \n\n[Install SAM CLI](command:aws.toolkit.installSAMCLI)\n\nDocker is an optional, third party tool that assists with local AWS Lambda runtime emulation. Docker is required to invoke Lambda functions on your local machine. \n\n[Install Docker (optional)](command:aws.toolkit.installDocker)\n\nEmulate your AWS cloud services locally with LocalStack to streamline testing in VS Code and CI environments. [Learn more](https://docs.localstack.cloud/aws/). \n\n[Install LocalStack (optional)](command:aws.toolkit.installLocalStack)",
     "AWS.toolkit.lambda.walkthrough.chooseTemplate.title": "Choose your application template",
     "AWS.toolkit.lambda.walkthrough.chooseTemplate.description": "Select a starter application, visually compose an application from scratch, open an existing application, or browse more application examples. \n\nInfrastructure Composer allows you to visually compose modern applications in the cloud. It will define the necessary permissions between resources when you drag a connection between them. \n\n[Initialize your project](command:aws.toolkit.lambda.initializeWalkthroughProject)",
     "AWS.toolkit.lambda.walkthrough.step1.title": "Iterate locally",

packages/core/src/awsService/appBuilder/activation.ts

@@ -13,7 +13,12 @@ import { activateViewsShared, registerToolView } from '../../awsexplorer/activat
 import { setContext } from '../../shared/vscode/setContext'
 import { fs } from '../../shared/fs/fs'
 import { AppBuilderRootNode } from './explorer/nodes/rootNode'
-import { initWalkthroughProjectCommand, walkthroughContextString, getOrInstallCliWrapper } from './walkthrough'
+import {
+    initWalkthroughProjectCommand,
+    walkthroughContextString,
+    getOrInstallCliWrapper,
+    installLocalStackExtension,
+} from './walkthrough'
 import { getLogger } from '../../shared/logger/logger'
 import path from 'path'
 import { TreeNode } from '../../shared/treeview/resourceTreeDataProvider'
@@ -142,6 +147,9 @@ async function registerAppBuilderCommands(context: ExtContext): Promise<void> {
         Commands.register('aws.toolkit.installDocker', async () => {
             await getOrInstallCliWrapper('docker', source)
         }),
+        Commands.register('aws.toolkit.installLocalStack', async () => {
+            await installLocalStackExtension(source)
+        }),
         Commands.register('aws.toolkit.lambda.setWalkthroughToAPI', async () => {
             await setWalkthrough('API')
         }),

packages/core/src/awsService/appBuilder/walkthrough.ts

@@ -16,7 +16,7 @@ import { ToolkitError } from '../../shared/errors'
 import { createSingleFileDialog } from '../../shared/ui/common/openDialog'
 import { fs } from '../../shared/fs/fs'
 import path from 'path'
-import { telemetry } from '../../shared/telemetry/telemetry'
+import { telemetry, ToolId } from '../../shared/telemetry/telemetry'
 
 import { minSamCliVersionForAppBuilderSupport } from '../../shared/sam/cli/samCliValidator'
 import { SamCliInfoInvocation } from '../../shared/sam/cli/samCliInfo'
@@ -347,3 +347,33 @@ export async function getOrInstallCliWrapper(toolId: AwsClis, source: string) {
         }
     })
 }
+
+export async function installLocalStackExtension(source: string) {
+    await telemetry.appBuilder_installTool.run(async (span) => {
+        // TODO: update `toolId` to "localstack" after updating the telemetry definitions: https://github.com/aws/aws-toolkit-common/blob/8c88537fae2ac7e6524fb2b29ae336c606850eeb/telemetry/definitions/commonDefinitions.json#L2215-L2221
+        const toolId: ToolId = 'sam-cli'
+        span.record({ source, toolId })
+        const extensionId = 'localstack.localstack'
+        const extension = vscode.extensions.getExtension(extensionId)
+        if (extension) {
+            void vscode.window.showInformationMessage(
+                localize(
+                    'AWS.toolkit.lambda.walkthrough.localStackExtension.alreadyInstalled',
+                    'LocalStack extension is already installed'
+                )
+            )
+        } else {
+            try {
+                await vscode.commands.executeCommand('workbench.extensions.installExtension', extensionId)
+                void vscode.window.showInformationMessage(
+                    localize(
+                        'AWS.toolkit.lambda.walkthrough.localStackExtension.installSuccessful',
+                        'LocalStack extension has been installed'
+                    )
+                )
+            } catch (err) {
+                throw ToolkitError.chain(err, 'Failed to install LocalStack extension')
+            }
+        }
+    })
+}

packages/core/src/test/awsService/appBuilder/walkthrough.test.ts

@@ -15,6 +15,7 @@ import {
     RuntimeLocationWizard,
     genWalkthroughProject,
     openProjectInWorkspace,
+    installLocalStackExtension,
 } from '../../../awsService/appBuilder/walkthrough'
 import { createWizardTester } from '../../shared/wizards/wizardTestUtils'
 import { fs } from '../../../shared'
@@ -460,5 +461,96 @@ describe('AppBuilder Walkthrough', function () {
                 toolId: 'sam-cli',
             })
         })
+
+        describe('Install LocalStack Extension', function () {
+            const expectedLocalStackToolId = 'sam-cli' // temporarily until toolkit-common changes
+
+            it('should show already installed message when extension exists', async function () {
+                const mockExtension = { id: 'localstack.localstack' }
+                sandbox
+                    .stub(vscode.extensions, 'getExtension')
+                    .withArgs('localstack.localstack')
+                    .returns(mockExtension as any)
+                const spyExecuteCommand = sandbox.spy(vscode.commands, 'executeCommand')
+
+                await installLocalStackExtension('test-source')
+
+                const message = await getTestWindow().waitForMessage(/LocalStack extension is already installed/)
+                message.close()
+
+                // Verify installation command was not called
+                sandbox.assert.neverCalledWith(spyExecuteCommand, 'workbench.extensions.installExtension')
+
+                // Verify telemetry
+                assertTelemetry({
+                    result: 'Succeeded',
+                    source: 'test-source',
+                    toolId: expectedLocalStackToolId, // Note: currently uses sam-cli as toolId per TODO comment
+                })
+            })
+
+            it('should successfully install extension when not present', async function () {
+                sandbox.stub(vscode.extensions, 'getExtension').withArgs('localstack.localstack').returns(undefined)
+                const spyExecuteCommand = sandbox.stub(vscode.commands, 'executeCommand').resolves()
+
+                await installLocalStackExtension('test-source')
+
+                const message = await getTestWindow().waitForMessage(/LocalStack extension has been installed/)
+                message.close()
+
+                // Verify installation command was called with correct extension ID
+                sandbox.assert.calledWith(
+                    spyExecuteCommand,
+                    'workbench.extensions.installExtension',
+                    'localstack.localstack'
+                )
+
+                // Verify telemetry
+                assertTelemetry({
+                    result: 'Succeeded',
+                    source: 'test-source',
+                    toolId: expectedLocalStackToolId,
+                })
+            })
+
+            it('should handle installation failure and throw ToolkitError', async function () {
+                sandbox.stub(vscode.extensions, 'getExtension').withArgs('localstack.localstack').returns(undefined)
+                const installError = new Error('Installation failed')
+                sandbox.stub(vscode.commands, 'executeCommand').rejects(installError)
+
+                await assert.rejects(installLocalStackExtension('test-source'), (error: any) => {
+                    assert.strictEqual(error.message, 'Failed to install LocalStack extension')
+                    assert.strictEqual(error.cause, installError)
+                    return true
+                })
+
+                // Verify telemetry is still recorded even on failure
+                assertTelemetry({
+                    result: 'Failed',
+                    source: 'test-source',
+                    toolId: expectedLocalStackToolId,
+                })
+            })
+
+            it('should record telemetry with correct source parameter', async function () {
+                const mockExtension = { id: 'localstack.localstack' }
+                sandbox
+                    .stub(vscode.extensions, 'getExtension')
+                    .withArgs('localstack.localstack')
+                    .returns(mockExtension as any)
+
+                await installLocalStackExtension('walkthrough-button')
+
+                const message = await getTestWindow().waitForMessage(/LocalStack extension is already installed/)
+                message.close()
+
+                // Verify telemetry includes the correct source
+                assertTelemetry({
+                    result: 'Succeeded',
+                    source: 'walkthrough-button',
+                    toolId: expectedLocalStackToolId,
+                })
+            })
+        })
     })
 })

packages/toolkit/.changes/next-release/Feature-b799e933-2707-4cd8-9217-6cdd46ee2b4a.json

@@ -0,0 +1,4 @@
+{
+	"type": "Feature",
+	"description": "Lambda AppBuilder: Now you can install LocalStack VS Code extension from the AppBuilder walkthrough"
+}