feat: add extension walkthrough

package.json

@@ -19,7 +19,8 @@
     "onView:electron-build-tools:configs",
     "onView:electron-build-tools:patches",
     "onView:electron-build-tools:docs",
-    "onView:electron-build-tools:electron"
+    "onView:electron-build-tools:electron",
+    "onWalkthrough:electron-build-tools"
   ],
   "categories": [
     "Extension Packs",
@@ -82,6 +83,12 @@
         "category": "Electron Build Tools",
         "enablement": "electron-build-tools:active && electron-build-tools:canBuild"
       },
+      {
+        "command": "electron-build-tools.installBuildTools",
+        "title": "Install Build Tools",
+        "category": "Electron Build Tools",
+        "enablement": "!electron-build-tools:build-tools-installed"
+      },
       {
         "command": "electron-build-tools.newConfig",
         "title": "New Config",
@@ -94,6 +101,11 @@
         "title": "Open Patch",
         "category": "Electron Build Tools"
       },
+      {
+        "command": "electron-build-tools.openWalkthrough",
+        "title": "Open Walkthrough",
+        "category": "Electron Build Tools"
+      },
       {
         "command": "electron-build-tools.refreshPatches",
         "title": "Refresh Patches",
@@ -326,10 +338,18 @@
           "command": "electron-build-tools.buildAdvanced",
           "when": "electron-build-tools:build-tools-installed"
         },
+        {
+          "command": "electron-build-tools.installBuildTools",
+          "when": "false"
+        },
         {
           "command": "electron-build-tools.openPatch",
           "when": "false"
         },
+        {
+          "command": "electron-build-tools.openWalkthrough",
+          "when": "false"
+        },
         {
           "command": "electron-build-tools.removeConfig",
           "when": "false"
@@ -572,12 +592,91 @@
     "viewsWelcome": [
       {
         "view": "electron-build-tools:welcome",
-        "contents": "In order to use the Electron Build Tools extension, you need the npm package @electron/build-tools, version 1.1.0 or newer, installed."
+        "contents": "In order to use the Electron Build Tools extension, you need the npm package @electron/build-tools, version 1.1.0 or newer, installed.\n[Open Walkthrough](command:electron-build-tools.openWalkthrough)"
       },
       {
         "view": "electron-build-tools:workspace",
         "contents": "An Electron checkout wasn't found in this workspace.\n[Open Folder](command:vscode.openFolder)"
       }
+    ],
+    "walkthroughs": [
+      {
+        "id": "electron-build-tools",
+        "title": "Get Started with Electron Build Tools",
+        "description": "Learn about Electron Build Tools and the Electron Build Tools extension for VS Code",
+        "featuredFor": [
+          "ELECTRON_VERSION",
+          "src/ELECTRON_VERSION"
+        ],
+        "steps": [
+          {
+            "id": "electron-build-tools.install",
+            "title": "Install Electron Build Tools",
+            "description": "Install the ``@electron/build-tools`` npm package.\n[Install Electron Build Tools](command:electron-build-tools.installBuildTools)",
+            "media": {
+              "markdown": "resources/walkthrough/install-build-tools.md"
+            },
+            "completionEvents": [
+              "onContext:electron-build-tools:build-tools-installed"
+            ]
+          },
+          {
+            "id": "electron-build-tools.create-config",
+            "title": "Create a Build Tools config",
+            "description": "Create a config to start building Electron.\n[Create Config](command:electron-build-tools.newConfig)",
+            "media": {
+              "markdown": "resources/walkthrough/config.md"
+            },
+            "completionEvents": [
+              "onContext:electron-build-tools:active-config"
+            ]
+          },
+          {
+            "id": "electron-build-tools.sync",
+            "title": "Sync the Electron checkout",
+            "description": "The initial sync will download the source code and sync dependencies.\n[Sync](command:electron-build-tools.sync)",
+            "media": {
+              "markdown": "resources/walkthrough/sync-command.md"
+            },
+            "completionEvents": [
+              "onCommand:electron-build-tools.sync"
+            ]
+          },
+          {
+            "id": "electron-build-tools.open-workspace",
+            "title": "Open the Electron checkout",
+            "description": "Open the Electron checkout in the workspace to get started with Electron Build Tools extension features.\nThis can either be at the root level, ``src``, or in the Electron subfolder, ``src/electron``.\n[Open Folder](command:vscode.openFolder)",
+            "media": {
+              "markdown": "resources/walkthrough/empty.md"
+            },
+            "completionEvents": [
+              "onContext:electron-build-tools:is-electron-workspace"
+            ]
+          },
+          {
+            "id": "electron-build-tools.build",
+            "title": "Build Electron",
+            "description": "Build Electron from source.\n[Build](command:electron-build-tools.build)",
+            "media": {
+              "markdown": "resources/walkthrough/build.md"
+            },
+            "completionEvents": [
+              "onCommand:electron-build-tools.build"
+            ]
+          },
+          {
+            "id": "electron-build-tools.learn-more",
+            "title": "Learn more",
+            "description": "🎨 Explore all the features the Electron Build Tools extension has to offer by looking for \"Electron Build Tools\" in the [Command Palette](command:workbench.action.showCommands).\n ✨ Take a look at the [Changelog](https://marketplace.visualstudio.com/items/dsanders11.vscode-electron-build-tools/changelog) to learn more about the latest features. \n \n[Learn More](https://github.com/dsanders11/vscode-electron-build-tools)",
+            "media": {
+              "markdown": "resources/walkthrough/empty.md"
+            },
+            "completionEvents": [
+              "onStepSelected"
+            ]
+          }
+        ]
+      }
     ]
   },
   "extensionPack": [

resources/walkthrough/build.md

@@ -0,0 +1,3 @@
+# Build Electron
+
+TODO

resources/walkthrough/config.md

@@ -0,0 +1,14 @@
+# Build Tools Config
+
+Build configs define the build configuration, e.g. the path to the source
+code, compile-time options, your GitHub fork, and so on.
+
+Each build config has a unique name, chosen by you to use as a mnemonic when
+switching between build configs. This is the name's only purpose, so choose
+whatever you find easiest to work with - whether it's `electron`,
+`6-1-x--testing`, or `chocolate-onion-popsicle`.
+
+Each build also needs a root directory. All the source code and built files
+will be stored somewhere beneath it. If you want to make multiple build types
+of the same branch, you can reuse an existing root to share it between build
+configs.

resources/walkthrough/install-build-tools.md

@@ -0,0 +1,41 @@
+# Electron Build Tools
+
+## What Is It?
+
+Electron Build Tools is a command-line interface (CLI) to help build Electron
+from source, and has other helper commands for common development tasks. This
+VS Code extension provides a deep integration of Electron's build tools into
+VS Code, providing a graphical user interface (GUI) for the most common
+commands, user-friendly views of tests and patches, and other handy helpers.
+
+You can learn more about the Electron Build Tools CLI
+[here](https://github.com/electron/build-tools).
+
+## Prerequisites
+
+A handful of prerequisites, such as Git, Node.js, and npm, are required for
+building Electron itself; these can be found in [Platform Prerequisites].
+
+Electron Build Tools is configured to use Yarn, so please
+[install it to your system](https://yarnpkg.com/lang/en/docs/install/).
+
+## Installing
+
+For convenience, you can use the "Install Build Tools" button on this step
+to install the `@electron/build-tools` package for you.
+
+If you want to manually install it, from here on you'll need a command-line
+prompt. On Mac and Linux, this will be a terminal with a shell, e.g. bash or
+zsh. You can also use these on Windows if you install them, or use built-in
+tools like Windows' [Command Prompt].
+
+Please note that build tools (due to nested dependencies) might not work
+properly in powershell, please use `cmd` on Windows for optimum results.
+
+```sh
+# Install build-tools package globally:
+yarn global add @electron/build-tools
+```
+
+[Command Prompt]: https://docs.microsoft.com/en-us/windows-server/administration/windows-commands/windows-commands#command-shell-overview
+[Platform Prerequisites]: https://electronjs.org/docs/development/build-instructions-gn#platform-prerequisites

resources/walkthrough/sync-command.md

@@ -0,0 +1,34 @@
+# The Sync Command
+
+## Initial Sync
+
+Getting the source code is a lot more than cloning `electron/electron`.
+Electron is built on top of Chromium (with Electron patches) and Node
+(with more Electron patches). A source tree needs to have all of the
+above **and** for their versions to be in sync with each other. Electron
+uses Chromium's [Depot Tools] and [GN] for wrangling and building the code.
+
+After creating a new config, the initial sync will perform all of these steps
+and get the Electron checkout ready for building. It will take a while to
+download everything and initialize it, potentially hours depending on your
+internet speed, so you might want to take a caffeine break after kicking it
+off. There's a handy progress bar to let you know how things are going:
+
+TODO: Insert picture of progress bar.
+
+## When To Use Sync
+
+TODO:
+
+* When switching branches
+
+## Force Sync
+
+An interrupted sync may leave the source tree in a bad state which will cause
+future syncs to fail. To remedy this situation, you can run a force sync which
+will clean up the state of the source tree before syncing.
+
+TODO: Insert picture of force sync in command palette
+
+[Depot Tools]: https://commondatastorage.googleapis.com/chrome-infra-docs/flat/depot_tools/docs/html/depot_tools_tutorial.html#_setting_up
+[GN]: https://chromium.googlesource.com/chromium/src/tools/gn/+/48062805e19b4697c5fbd926dc649c78b6aaa138/README.md

src/extension.ts

@@ -28,6 +28,7 @@ import {
   drillDown,
   findElectronRoot,
   getPatchesConfigFile,
+  installBuildTools,
   isBuildToolsInstalled,
   OptionalFeature,
   setContext,
@@ -172,7 +173,40 @@ export async function activate(context: vscode.ExtensionContext) {
     vscode.window.registerTreeDataProvider(
       viewIds.HELP,
       new HelpTreeDataProvider(context.extensionUri)
-    )
+    ),
+    vscode.commands.registerCommand(
+      `${commandPrefix}.installBuildTools`,
+      async () => {
+        vscode.window.withProgress(
+          {
+            location: vscode.ProgressLocation.Notification,
+            title: "Installing Electron Build Tools",
+            cancellable: true,
+          },
+          async (progress, token) => {
+            const success = await installBuildTools(token);
+
+            if (success !== undefined) {
+              if (success) {
+                vscode.window.showInformationMessage(
+                  "Successfully installed Electron Build Tools"
+                );
+              } else {
+                vscode.window.showErrorMessage(
+                  "Failed to install Electron Build Tools"
+                );
+              }
+            }
+          }
+        );
+      }
+    ),
+    vscode.commands.registerCommand(`${commandPrefix}.openWalkthrough`, () => {
+      return vscode.commands.executeCommand(
+        "workbench.action.openWalkthrough",
+        "dsanders11.vscode-electron-build-tools#electron-build-tools"
+      );
+    })
   );
 
   const workspaceFolders = vscode.workspace.workspaceFolders;

src/utils.ts

@@ -666,3 +666,39 @@ export function positionAt(content: string, offset: number) {
 
   return new vscode.Position(lines.length - 1, lastLine.length);
 }
+
+export async function installBuildTools(token: vscode.CancellationToken) {
+  const task = new vscode.Task(
+    { type: "electron-build-tools", task: "install-build-tools" },
+    vscode.TaskScope.Workspace,
+    "Install Build Tools",
+    "electron-build-tools",
+    new vscode.ProcessExecution("yarn", [
+      "global",
+      "add",
+      "@electron/build-tools",
+    ])
+  );
+  task.presentationOptions = {
+    reveal: vscode.TaskRevealKind.Silent,
+    echo: true,
+    clear: true,
+  };
+
+  const disposables: vscode.Disposable[] = [];
+
+  return new Promise<boolean | undefined>(async (resolve) => {
+    vscode.tasks.onDidEndTaskProcess(({ execution, exitCode }) => {
+      if (execution === taskExecution) {
+        resolve(exitCode ? exitCode === 0 : undefined);
+        disposables.forEach((disposable) => disposable.dispose());
+      }
+    }, disposables);
+
+    const taskExecution = await vscode.tasks.executeTask(task);
+
+    token.onCancellationRequested(() => {
+      taskExecution.terminate();
+    }, disposables);
+  });
+}

src/views/help.ts

@@ -1,6 +1,11 @@
 import * as vscode from "vscode";
 
-import { buildToolsRepository, extensionId, repositoryUrl } from "../constants";
+import {
+  buildToolsRepository,
+  commandPrefix,
+  extensionId,
+  repositoryUrl,
+} from "../constants";
 
 export class HelpTreeDataProvider
   implements vscode.TreeDataProvider<vscode.TreeItem>
@@ -26,6 +31,16 @@ export class HelpTreeDataProvider
         title: "Report Issue",
       };
 
+      const walkthroughTreeItem = new vscode.TreeItem(
+        "Open Extension Walkthrough",
+        vscode.TreeItemCollapsibleState.None
+      );
+      walkthroughTreeItem.iconPath = new vscode.ThemeIcon("extensions");
+      walkthroughTreeItem.command = {
+        command: `${commandPrefix}.openWalkthrough`,
+        title: "Open Walkthrough",
+      };
+
       return [
         new LinkHelpTreeItem(
           "Extension Documentation",
@@ -52,6 +67,7 @@ export class HelpTreeDataProvider
           },
           vscode.Uri.parse(buildToolsRepository)
         ),
+        walkthroughTreeItem,
         new LinkHelpTreeItem(
           "Review Issues",
           new vscode.ThemeIcon("remote-explorer-review-issues"),