amazonq: vscode walkthrough (aws#4739)

nkomonen-amazon · web-flow · commit cae6147497b7 · 2024-04-19T16:33:47.000-04:00
- Creates the Amazon Q walkthrough
- GIFs still need to be created, we are waiting on those but we can merge for now
- When the user logs in to Amazon Q the first time they will be shown the walkthrough page. It will never show again
- We have telemetry for when the walkthrough is shown through our "first login" automation, and when certain events are triggered in the walkthrough such as opening the chat

Signed-off-by: Nikolas Komonen &lt;nkomonen@amazon.com&gt;
diff --git a/packages/amazonq/package.json b/packages/amazonq/package.json
@@ -798,7 +798,58 @@
                     "fontCharacter": "\\f1c3"
                 }
             }
-        }
+        },
+        "walkthroughs": [
+            {
+                "id": "aws.amazonq.walkthrough",
+                "title": "Meet Amazon Q",
+                "description": "Your AI assistant",
+                "steps": [
+                    {
+                        "id": "aws.amazonq.walkthrough.chat",
+                        "title": "Ask using chat",
+                        "description": "Amazon Q answers software development questions, writes code based on your current file, and cites sources.\n\nUse the right-click menu for quick commands.\n\n[Open Chat](command:_aws.amazonq.walkthrough.focusChat)",
+                        "media": {
+                            "image": "placeholder.jpg",
+                            "altText": "Gif of the right click context menu opening Amazon Q chat"
+                        },
+                        "completionEvents": [
+                            "onCommand:_aws.amazonq.walkthrough.focusChat"
+                        ]
+                    },
+                    {
+                        "id": "aws.amazonq.walkthrough.inlineSuggestions",
+                        "title": "Get inline code suggestions",
+                        "description": "Amazon Q suggests code as you type based on your open files. Accepted suggestions from licensed code will go into the 'Code Reference Log'.",
+                        "media": {
+                            "image": "placeholder.jpg",
+                            "altText": "Gif of Amazon Q Inline Suggestions feature"
+                        }
+                    },
+                    {
+                        "id": "aws.amazonq.walkthrough.securityScan",
+                        "title": "Check for security vulnerabilities",
+                        "description": "Amazon Q scans your code to identify security vulnerabilities and suggests fixes.",
+                        "media": {
+                            "image": "placeholder.jpg",
+                            "altText": "Gif of a security scan"
+                        }
+                    },
+                    {
+                        "id": "aws.amazonq.walkthrough.settings",
+                        "title": "Access settings and options",
+                        "description": "Pause inline suggestions, open the Code Reference Log, access Settings, and more from the Amazon Q menu.\n\n[Open the status bar menu](command:_aws.amazonq.walkthrough.listCommands)",
+                        "media": {
+                            "image": "placeholder.jpg",
+                            "altText": "Gif of opening the Amazon Q status bar menu"
+                        },
+                        "completionEvents": [
+                            "onCommand:_aws.amazonq.walkthrough.listCommands"
+                        ]
+                    }
+                ]
+            }
+        ]
     },
     "engines": {
         "npm": "^10.1.0",
diff --git a/packages/amazonq/placeholder.jpg b/packages/amazonq/placeholder.jpg
diff --git a/packages/core/src/amazonq/activation.ts b/packages/core/src/amazonq/activation.ts
@@ -5,7 +5,7 @@
 
 import * as vscode from 'vscode'
 import { ExtensionContext, window } from 'vscode'
-import { AmazonQChatViewProvider } from './webview/webView'
+import { AmazonQChatViewProvider, focusAmazonQChatWalkthrough } from './webview/webView'
 import { init as cwChatAppInit } from '../codewhispererChat/app'
 import { init as featureDevChatAppInit } from '../amazonqFeatureDev/app'
 import { init as gumbyChatAppInit } from '../amazonqGumby/app'
@@ -17,6 +17,8 @@ import { activateBadge } from './util/viewBadgeHandler'
 import { telemetry } from '../shared/telemetry/telemetry'
 import { focusAmazonQPanel } from '../auth/ui/vue/show'
 import { amazonQHelpUrl } from '../shared/constants'
+import { openAmazonQWalkthrough } from './onboardingPage/walkthrough'
+import { listCodeWhispererCommandsWalkthrough } from '../codewhisperer/ui/statusBarMenu'
 
 export async function activate(context: ExtensionContext) {
     const appInitContext = DefaultAmazonQAppInitContext.instance
@@ -37,7 +39,10 @@ export async function activate(context: ExtensionContext) {
             webviewOptions: {
                 retainContextWhenHidden: true,
             },
-        })
+        }),
+        focusAmazonQChatWalkthrough.register(),
+        openAmazonQWalkthrough.register(),
+        listCodeWhispererCommandsWalkthrough.register()
     )
 
     amazonQWelcomeCommand.register(context, cwcWebViewToAppsPublisher)
diff --git a/packages/core/src/amazonq/onboardingPage/walkthrough.ts b/packages/core/src/amazonq/onboardingPage/walkthrough.ts
@@ -0,0 +1,37 @@
+/*!
+ * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import globals from '../../shared/extensionGlobals'
+import { VSCODE_EXTENSION_ID } from '../../shared/extensions'
+import { Commands } from '../../shared/vscode/commands2'
+import vscode from 'vscode'
+
+/**
+ * Show the Amazon Q walkthrough one time forever when the user adds an Amazon Q connection.
+ * All subsequent calls to this do nothing.
+ */
+export async function showAmazonQWalkthroughOnce(
+    state = globals.context.globalState,
+    showWalkthrough = () => openAmazonQWalkthrough.execute()
+) {
+    const hasShownWalkthroughId = 'aws.amazonq.hasShownWalkthrough'
+    const hasShownWalkthrough = state.get(hasShownWalkthroughId, false)
+    if (hasShownWalkthrough) {
+        return
+    }
+    await state.update(hasShownWalkthroughId, true)
+    await showWalkthrough()
+}
+
+/**
+ * Opens the Amazon Q Walkthrough.
+ * We wrap the actual command so that we can get telemetry from it.
+ */
+export const openAmazonQWalkthrough = Commands.declare(`_aws.amazonq.walkthrough.show`, () => async () => {
+    await vscode.commands.executeCommand(
+        'workbench.action.openWalkthrough',
+        `${VSCODE_EXTENSION_ID.amazonq}#aws.amazonq.walkthrough`
+    )
+})
diff --git a/packages/core/src/amazonq/webview/webView.ts b/packages/core/src/amazonq/webview/webView.ts
@@ -21,6 +21,8 @@ import { MessagePublisher } from '../messages/messagePublisher'
 import { TabType } from './ui/storages/tabsStorage'
 import { deactivateInitialViewBadge, shouldShowBadge } from '../util/viewBadgeHandler'
 import { telemetry } from '../../shared/telemetry/telemetry'
+import { Commands } from '../../shared/vscode/commands2'
+import vscode from 'vscode'
 
 export class AmazonQChatViewProvider implements WebviewViewProvider {
     public static readonly viewType = 'aws.AmazonQChatView'
@@ -79,3 +81,8 @@ export class AmazonQChatViewProvider implements WebviewViewProvider {
         deactivateInitialViewBadge()
     }
 }
+
+/** For use by the walkthrough page only. We need this for telemetry. */
+export const focusAmazonQChatWalkthrough = Commands.declare('_aws.amazonq.walkthrough.focusChat', () => async () => {
+    await vscode.commands.executeCommand('aws.AmazonQChatView.focus')
+})
diff --git a/packages/core/src/codewhisperer/ui/statusBarMenu.ts b/packages/core/src/codewhisperer/ui/statusBarMenu.ts
@@ -109,3 +109,14 @@ export const listCodeWhispererCommands = Commands.declare({ id: listCodeWhispere
         ignoreFocusOut: false,
     }).prompt()
 })
+
+/**
+ * Does what {@link listCodeWhispererCommands} does, must only be used by the walkthrough for telemetry
+ * purposes.
+ */
+export const listCodeWhispererCommandsWalkthrough = Commands.declare(
+    `_aws.amazonq.walkthrough.listCommands`,
+    () => async () => {
+        await listCodeWhispererCommands.execute()
+    }
+)
diff --git a/packages/core/src/codewhisperer/util/authUtil.ts b/packages/core/src/codewhisperer/util/authUtil.ts
@@ -37,6 +37,7 @@ import { indent } from '../../shared/utilities/textUtilities'
 import { VSCODE_EXTENSION_ID } from '../../shared/extensions'
 import { isExtensionActive } from '../../shared/utilities'
 import { showReauthenticateMessage } from '../../shared/utilities/messages'
+import { showAmazonQWalkthroughOnce } from '../../amazonq/onboardingPage/walkthrough'
 
 /** Backwards compatibility for connections w pre-chat scopes */
 export const codeWhispererCoreScopes = [...scopesSsoAccountAccess, ...scopesCodeWhispererCore]
@@ -251,6 +252,8 @@ export class AuthUtil {
             conn = await this.auth.reauthenticate(conn)
         }
 
+        await showAmazonQWalkthroughOnce()
+
         return this.secondaryAuth.useNewConnection(conn)
     }
 
@@ -270,6 +273,8 @@ export class AuthUtil {
             conn = await this.auth.reauthenticate(conn)
         }
 
+        await showAmazonQWalkthroughOnce()
+
         return this.secondaryAuth.useNewConnection(conn)
     }
 
diff --git a/packages/core/src/test/amazonq/onboardingPage/walkthrough.test.ts b/packages/core/src/test/amazonq/onboardingPage/walkthrough.test.ts
@@ -0,0 +1,24 @@
+/*!
+ * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import assert from 'assert'
+import { showAmazonQWalkthroughOnce } from '../../../amazonq/onboardingPage/walkthrough'
+import { FakeMemento } from '../../fakeExtensionContext'
+import sinon from 'sinon'
+
+describe('showAmazonQWalkthroughOnce', function () {
+    it('only shows once', async function () {
+        const state = new FakeMemento()
+        const showWalkthroughStub = sinon.stub()
+        assert.deepStrictEqual(showWalkthroughStub.callCount, 0)
+        await showAmazonQWalkthroughOnce(state, showWalkthroughStub)
+        // Show walkthrough since our state indicates we haven't shown before
+        assert.deepStrictEqual(showWalkthroughStub.callCount, 1)
+
+        await showAmazonQWalkthroughOnce(state, showWalkthroughStub)
+        // On the second call we do not show again since we've shown before.
+        assert.deepStrictEqual(showWalkthroughStub.callCount, 1)
+    })
+})
diff --git a/packages/core/src/test/codewhisperer/util/authUtil.test.ts b/packages/core/src/test/codewhisperer/util/authUtil.test.ts
@@ -14,9 +14,10 @@ import {
 import { getTestWindow } from '../../shared/vscode/window'
 import { SeverityLevel } from '../../shared/vscode/message'
 import { createBuilderIdProfile, createSsoProfile, createTestAuth } from '../../credentials/testUtil'
-import { captureEventOnce } from '../../testUtil'
+import { captureEventOnce, tryRegister } from '../../testUtil'
 import { Connection, isAnySsoConnection, isBuilderIdConnection } from '../../../auth/connection'
 import { Auth } from '../../../auth/auth'
+import { openAmazonQWalkthrough } from '../../../amazonq/onboardingPage/walkthrough'
 
 const enterpriseSsoStartUrl = 'https://enterprise.awsapps.com/start'
 
@@ -27,6 +28,7 @@ describe('AuthUtil', async function () {
     beforeEach(async function () {
         auth = createTestAuth()
         authUtil = new AuthUtil(auth)
+        tryRegister(openAmazonQWalkthrough)
     })
 
     afterEach(async function () {

Original file line number	Diff line number	Diff line change
`@@ -37,6 +37,7 @@ import { indent } from '../../shared/utilities/textUtilities'`
`37`	`37`	`import { VSCODE_EXTENSION_ID } from '../../shared/extensions'`
`38`	`38`	`import { isExtensionActive } from '../../shared/utilities'`
`39`	`39`	`import { showReauthenticateMessage } from '../../shared/utilities/messages'`
	`40`	`+import { showAmazonQWalkthroughOnce } from '../../amazonq/onboardingPage/walkthrough'`
`40`	`41`
`41`	`42`	`/** Backwards compatibility for connections w pre-chat scopes */`
`42`	`43`	`export const codeWhispererCoreScopes = [...scopesSsoAccountAccess, ...scopesCodeWhispererCore]`
`@@ -251,6 +252,8 @@ export class AuthUtil {`
`251`	`252`	`conn = await this.auth.reauthenticate(conn)`
`252`	`253`	`}`
`253`	`254`
	`255`	`+ await showAmazonQWalkthroughOnce()`
	`256`	`+`
`254`	`257`	`return this.secondaryAuth.useNewConnection(conn)`
`255`	`258`	`}`
`256`	`259`
`@@ -270,6 +273,8 @@ export class AuthUtil {`
`270`	`273`	`conn = await this.auth.reauthenticate(conn)`
`271`	`274`	`}`
`272`	`275`
	`276`	`+ await showAmazonQWalkthroughOnce()`
	`277`	`+`
`273`	`278`	`return this.secondaryAuth.useNewConnection(conn)`
`274`	`279`	`}`
`275`	`280`