Cursorless tutorial ced

.vscode/tasks.json

@@ -32,6 +32,16 @@
       },
       "group": "build"
     },
+    {
+      "label": "Build tutorial webview",
+      "type": "npm",
+      "script": "compile:dev",
+      "path": "packages/cursorless-vscode-tutorial-webview",
+      "presentation": {
+        "reveal": "silent"
+      },
+      "group": "build"
+    },
     {
       "label": "Build test harness",
       "type": "npm",
@@ -57,6 +67,7 @@
       "type": "npm",
       "script": "populate-dist",
       "path": "packages/cursorless-vscode",
+      "dependsOn": ["Build tutorial webview"],
       "presentation": {
         "reveal": "silent"
       },

cursorless-talon/src/cursorless.py

@@ -21,3 +21,9 @@ def private_cursorless_show_command_statistics():
         actions.user.private_cursorless_run_rpc_command_no_wait(
             "cursorless.analyzeCommandHistory"
         )
+
+    def private_cursorless_start_tutorial():
+        """Start Cursorless tutorial"""
+        actions.user.private_cursorless_run_rpc_command_no_wait(
+            "cursorless.tutorial.start", "unit-2-basic-coding"
+        )

cursorless-talon/src/cursorless.talon

@@ -46,3 +46,6 @@ bar {user.cursorless_homophone}:
 
 {user.cursorless_homophone} stats:
     user.private_cursorless_show_command_statistics()
+
+{user.cursorless_homophone} tutorial:
+    user.private_cursorless_start_tutorial()

data/playground/tutorial/extra-cloning-a-talon-list.py

@@ -0,0 +1,9 @@
+from talon import Context, Module
+
+mod = Module()
+ctx = Context()
+
+mod.list("cursorless_walkthrough_list", desc="My tutorial list")
+ctx.list["user.cursorless_walkthrough_list"] = {
+    "spoken form": "whatever",
+}

data/playground/tutorial/unit-1-basics.txt

@@ -0,0 +1,11 @@
+==================================================
+==========                              ==========
+==========    Welcome to Cursorless!    ==========
+==========                              ==========
+==========   Let's start using marks    ==========
+==========                              ==========
+==========  so we can navigate around   ==========
+==========                              ==========
+==========  without lifting a finger!   ==========
+==========                              ==========
+==================================================

data/playground/tutorial/unit-2-basic-coding.py

@@ -0,0 +1,13 @@
+def print_color(color, invert=False):
+    if invert:
+        print(invert_color(color))
+    else:
+        print(color)
+
+
+def invert_color(color):
+    if color == "black":
+        return "white"
+
+
+print_color("black")

packages/common/src/cursorlessCommandIds.ts

@@ -47,6 +47,7 @@ export const cursorlessCommandIds = [
   "cursorless.toggleDecorations",
   "cursorless.showScopeVisualizer",
   "cursorless.hideScopeVisualizer",
+  "cursorless.tutorial.start",
   "cursorless.analyzeCommandHistory",
 ] as const satisfies readonly `cursorless.${string}`[];
 
@@ -81,6 +82,7 @@ export const cursorlessCommandDescriptions: Record<
     "Analyze collected command history",
   ),
 
+  ["cursorless.tutorial.start"]: new HiddenCommand("Start a tutorial"),
   ["cursorless.command"]: new HiddenCommand("The core cursorless command"),
   ["cursorless.showQuickPick"]: new HiddenCommand(
     "Pop up a quick pick of all cursorless commands",

packages/common/src/index.ts

@@ -49,7 +49,9 @@ export * from "./types/HatTokenMap";
 export * from "./types/ScopeProvider";
 export * from "./types/SpokenForm";
 export * from "./types/commandHistory";
+export * from "./types/tutorial.types";
 export * from "./util/textFormatters";
+export * from "./util/serializedMarksToTokenHats";
 export * from "./types/snippet.types";
 export * from "./testUtil/fromPlainObject";
 export * from "./testUtil/spyToPlainObject";

packages/common/src/types/tutorial.types.ts

@@ -0,0 +1,16 @@
+export type TutorialId = "introduction";
+
+interface PickingTutorialState {
+  type: "pickingTutorial";
+}
+
+export interface ActiveTutorialState {
+  type: "doingTutorial";
+  title: string;
+  tutorialId: TutorialId;
+  stepNumber: number;
+  stepContent: string;
+  stepCount: number;
+}
+
+export type TutorialState = PickingTutorialState | ActiveTutorialState;

packages/common/src/util/serializedMarksToTokenHats.ts

@@ -0,0 +1,36 @@
+import { plainObjectToRange } from "../testUtil/fromPlainObject";
+import { splitKey } from "./splitKey";
+import { SerializedMarks } from "./toPlainObject";
+import { TextEditor } from "../types/TextEditor";
+import { TokenHat } from "../types/HatTokenMap";
+
+export function serializedMarksToTokenHats(
+  marks: SerializedMarks | undefined,
+  editor: TextEditor,
+): TokenHat[] {
+  if (marks == null) {
+    return [];
+  }
+
+  return Object.entries(marks).map(([key, token]) => {
+    const { hatStyle, character } = splitKey(key);
+    const range = plainObjectToRange(token);
+
+    return {
+      hatStyle,
+      grapheme: character,
+      token: {
+        editor,
+        range,
+        offsets: {
+          start: editor.document.offsetAt(range.start),
+          end: editor.document.offsetAt(range.end),
+        },
+        text: editor.document.getText(range),
+      },
+
+      // NB: We don't care about the hat range for this test
+      hatRange: range,
+    };
+  });
+}

packages/cursorless-engine/src/api/CursorlessEngineApi.ts

@@ -9,6 +9,7 @@ import type {
 import type { CommandRunner } from "../CommandRunner";
 import type { Snippets } from "../core/Snippets";
 import type { StoredTargetMap } from "../core/StoredTargets";
+import { Tutorial } from "./Tutorial";
 
 export interface CursorlessEngine {
   commandApi: CommandApi;
@@ -17,6 +18,7 @@ export interface CursorlessEngine {
   storedTargets: StoredTargetMap;
   hatTokenMap: HatTokenMap;
   snippets: Snippets;
+  tutorial: Tutorial;
   injectIde: (ide: IDE | undefined) => void;
   runIntegrationTests: () => Promise<void>;
   addCommandRunnerDecorator: (

packages/cursorless-engine/src/api/Tutorial.ts

@@ -0,0 +1,55 @@
+import { TutorialId } from "@cursorless/common";
+
+export interface TutorialContent {
+  /**
+   * The title of the tutorial
+   */
+  title: string;
+
+  /**
+   * The steps of the current tutorial
+   */
+  steps: Array<TutorialStep>;
+}
+
+export interface RawTutorialContent {
+  /**
+   * The title of the tutorial
+   */
+  title: string;
+
+  /**
+   * The steps of the current tutorial
+   */
+  steps: string[];
+}
+
+export interface TutorialStep {
+  /**
+   * The text content of the current step
+   */
+  content: string;
+
+  /**
+   * The path to the yaml file that should be used to setup the current step (if
+   * any). The path is relative to the tutorial directory for the given tutorial.
+   */
+  fixturePath?: string;
+}
+
+export interface TutorialSetupStepArg {
+  /**
+   * The id of the current tutorial
+   */
+  tutorialId: string;
+
+  /**
+   * The yaml file for the current step
+   */
+  fixturePath: string;
+}
+
+export interface Tutorial {
+  getContent(id: TutorialId): Promise<TutorialContent>;
+  setupStep(arg: TutorialSetupStepArg): Promise<void>;
+}

packages/cursorless-engine/src/core/IndividualHatMap.ts

@@ -58,7 +58,7 @@ export class IndividualHatMap implements ReadOnlyHatMap {
   }
 
   /**
-   * Overwrites the hat assignemnt for this hat token map.
+   * Overwrites the hat assignment for this hat token map.
    *
    * @param tokenHats The new hat assignments
    */