feat: add welcome page

Author: ivangabriele

.eslintrc

@@ -5,8 +5,6 @@
     "project": "./tsconfig.json"
   },
   "rules": {
-    "no-console": ["warn", { "allow": ["debug", "error", "info", "warn"] }],
-
     "import/no-extraneous-dependencies": "off",
 
     "@typescript-eslint/no-unused-vars": ["error", { "argsIgnorePattern": "^_" }]

__mocks__/vscode.ts

@@ -1,5 +1,13 @@
 // import type { WorkspaceFolder } from 'vscode'
 
+export const env = {
+  openExternal: jest.fn(),
+}
+
+export const Uri = {
+  parse: jest.fn(value => value),
+}
+
 export const workspace = {
   openTextDocument: jest.fn().mockResolvedValue({
     getText: jest.fn().mockReturnValue('Document source.'),
@@ -16,5 +24,8 @@ export const workspace = {
 }
 
 export const window = {
+  createOutputChannel: jest.fn(() => ({
+    appendLine: jest.fn(),
+  })),
   showErrorMessage: jest.fn(),
 }

docs/WELCOME.md

@@ -8,9 +8,7 @@
 - [Chrome](https://chrome.google.com/webstore/detail/openai-forge/nnppeeohaoogddcihgdpcolkmibbkked)
 - [Firefox](https://addons.mozilla.org/en-US/firefox/addon/openai-forge/)
 
-### 2. Open a workspace (if not already done)
-
-### 3. Configure the Evaluator
+### 2. Configure the Evaluator
 
 What the heck is an **Evaluator**?
 
@@ -21,9 +19,27 @@ OpenAI Forge use this command to detect errors in your code and send them to Cha
 This command is called:
 `OpenAI Forge: Evaluate errors and send them with the current document or stack` (<kbd>SHIFT + F, E</kbd>).
 
-### 4. Open a [ChatGPT](https://chat.openai.com) chat in your browser
+***Example:***
+
+> **⚠️ IMPORTANT: You need to split ALL the command subcommand and arguments in `commandArgs`.**
+
+`.vscode/settings.json`
 
-### 5. Add a few documents to your stack (or not)
+```json
+{
+  'openai-forge.customEvaluators': [
+    {
+      command: 'npm',
+      commandArgs: ['run', 'build'],
+      extensions: ['.js', '.jsx', '.ts', '.tsx'],
+    },
+  ],
+}
+```
+
+### 3. Open a [ChatGPT](https://chat.openai.com) chat in your browser
+
+### 4. Add a few documents to your stack (or not)
 
 Run the command `OpenAI Forge: Add/Remove current document to/from the stack` (<kbd>SHIFT + F, A</kbd>)
 to select/unselect your currently edited document.
@@ -35,18 +51,22 @@ You can see them in the status bar:
 
 Or don't, if you just want to send your currently edited document alone.
 
-### 6. Send them to ChatGPT
+### 5. Send them to ChatGPT
 
 Run the command `OpenAI Forge: Send current document or stack` (<kbd>SHIFT + F, S</kbd>).
 
-### 7. Useful Key Bindings
+### 6. Useful Key Bindings
 
 All OpenAI Forge default key bindings start with <kbd>SHIFT + F</kbd> (**F** for **F**orge):
 
 - <kbd>SHIFT + F, A</kbd>: `OpenAI Forge: Add/Remove current document to/from the stack`
 - <kbd>SHIFT + F, E</kbd>: `OpenAI Forge: Evaluate errors and send them with the current document or stack`
 - <kbd>SHIFT + F, S</kbd>: `OpenAI Forge: Send current document or stack`
 
-### 8. Star [my repo](https://github.com/ivangabriele/openai-forge-vsce) if you like it 🥰
+### 7. Star [my repo](https://github.com/ivangabriele/openai-forge-vsce) if you like it 🥰
+
+### 8. May the Forge be with you 🔨
 
-### 9. May the Forge be with you 🔨!
+- Post your ideas and questions [there](https://github.com/ivangabriele/openai-forge-vsce/discussions).
+- Post your issues [there](https://github.com/ivangabriele/openai-forge-vsce/issues).
+- If there is an internal error, you should be able to find it in **Output > OpenAI Forge**.

package.json

@@ -58,6 +58,7 @@
     "rollup-plugin-swc3": "0.8.2",
     "semantic-release": "21.0.7",
     "tslib": "2.6.0",
+    "type-fest": "4.0.0",
     "typescript": "5.1.6",
     "ws": "8.13.0"
   },
@@ -119,7 +120,7 @@
                 "description": "Source code file extensions triggering this evaluator before being sent to ChatGPT. Examples: `[\".rs\"]`, `[\".js\", \".ts\"]`.",
                 "items": {
                   "type": "string",
-                  "pattern": "^\\.[a-z]$"
+                  "pattern": "^\\.[a-z]+$"
                 },
                 "minItems": 1
               },

src/commands/welcome.ts

@@ -0,0 +1,66 @@
+import { join } from 'path'
+import { Position, Range, ViewColumn, WorkspaceEdit, window, workspace } from 'vscode'
+
+import { DocumentationPath } from '../constants'
+import { handleMessageItems } from '../helpers/handleMessageItems'
+import { isEmpty } from '../helpers/isEmpty'
+import { GlobalStateKey, getGlobalStateManager } from '../libs/GlobalStateManager'
+import { MessageItemType, type MessageButton } from '../types'
+import { getUserWorkspaceRootPath } from '../utils/getUserWorkspaceRootPath'
+import { showDocumentation } from '../utils/showDocumentation'
+
+const HIDE_MESSAGE_BUTTON: MessageButton = {
+  action: async () => {
+    await getGlobalStateManager().set(GlobalStateKey.ONBOARDING__HIDE_WELCOME_PAGE, true)
+  },
+  label: 'Never show welcome page again',
+  type: MessageItemType.BUTTON,
+}
+
+export async function welcome() {
+  const isWelcomePageHidden = await getGlobalStateManager().get(GlobalStateKey.ONBOARDING__HIDE_WELCOME_PAGE)
+  if (isWelcomePageHidden) {
+    return
+  }
+
+  await showDocumentation(DocumentationPath.WELCOME)
+
+  const workspaceSettingsPath = join(getUserWorkspaceRootPath(), '.vscode', 'settings.json')
+  const workspaceSettingsDocument = await workspace.openTextDocument(workspaceSettingsPath)
+  const workspaceSettingsText = workspaceSettingsDocument.getText()
+
+  if (!workspaceSettingsText.includes('openai-forge.customEvaluators')) {
+    const workspaceSettings = !isEmpty(workspaceSettingsText) ? JSON.parse(workspaceSettingsText) : {}
+    const suggestedWorkspaceSettings = JSON.stringify(
+      {
+        ...workspaceSettings,
+        'openai-forge.customEvaluators': [
+          {
+            command: 'npm',
+            commandArgs: ['run', 'build'],
+            extensions: ['.js', '.jsx', '.ts', '.tsx'],
+          },
+        ],
+      },
+      // eslint-disable-next-line no-null/no-null
+      null,
+      2,
+    )
+    const workspaceSettingsEdit = new WorkspaceEdit()
+    workspaceSettingsEdit.replace(
+      workspaceSettingsDocument.uri,
+      new Range(
+        new Position(0, 0),
+        workspaceSettingsDocument.lineAt(workspaceSettingsDocument.lineCount - 1).range.end,
+      ),
+      suggestedWorkspaceSettings,
+    )
+
+    await window.showTextDocument(workspaceSettingsDocument, ViewColumn.Two)
+    await workspace.applyEdit(workspaceSettingsEdit)
+
+    window
+      .showInformationMessage("Once you've read the welcome page:", HIDE_MESSAGE_BUTTON.label)
+      .then(handleMessageItems([HIDE_MESSAGE_BUTTON]))
+  }
+}

src/extension.ts

@@ -1,17 +1,14 @@
-import { join } from 'path'
-import { type ExtensionContext, workspace, commands, window, ViewColumn } from 'vscode'
+import { type ExtensionContext, workspace, commands, ExtensionMode } from 'vscode'
 
 import { addOrRemoveCurrentDocument } from './commands/addOrRemoveCurrentDocument'
 import { evaluateAndSendCurrentDocumentOrStack } from './commands/evaluateAndSendCurrentDocumentOrStack'
 import { sendCurrentDocument } from './commands/sendCurrentDocumentOrStack'
-import { DocumentationPath } from './constants'
+import { welcome } from './commands/welcome'
 import { handleError } from './helpers/handleError'
-import { initializeGlobalStateManager } from './libs/GlobalStateManager'
+import { getGlobalStateManager, initializeGlobalStateManager } from './libs/GlobalStateManager'
 import { server } from './libs/server'
 import { stackManager } from './libs/stackManager'
 import { stateManager } from './libs/stateManager'
-import { getUserWorkspaceRootPath } from './utils/getUserWorkspaceRootPath'
-import { showDocumentation } from './utils/showDocumentation'
 
 export async function activate(context: ExtensionContext) {
   try {
@@ -26,15 +23,9 @@ export async function activate(context: ExtensionContext) {
     // Global State
 
     await initializeGlobalStateManager(context)
-
-    // -------------------------------------------------------------------------
-    // Welcome Documentation
-
-    await showDocumentation(DocumentationPath.WELCOME)
-
-    const workspaceSettingsPath = join(getUserWorkspaceRootPath(), '.vscode', 'settings.json')
-    const settingsDocument = await workspace.openTextDocument(workspaceSettingsPath)
-    await window.showTextDocument(settingsDocument, ViewColumn.Two)
+    if (context.extensionMode === ExtensionMode.Development) {
+      await getGlobalStateManager().clear()
+    }
 
     // -------------------------------------------------------------------------
     // Commands
@@ -67,6 +58,11 @@ export async function activate(context: ExtensionContext) {
     // WebSocket Server
 
     server.start(context)
+
+    // -------------------------------------------------------------------------
+    // Welcome Documentation
+
+    await welcome()
   } catch (err) {
     handleError(err)
 

src/helpers/__tests__/handleMessageItem.test.ts

@@ -0,0 +1,45 @@
+import { Uri, env } from 'vscode'
+
+import { MessageItemType, type MessageButton, type MessageLink } from '../../types'
+import { handleMessageItems } from '../handleMessageItems'
+
+describe('handleMessageItems', () => {
+  const mockButtonAction = jest.fn()
+  const mockItems: Array<MessageButton | MessageLink> = [
+    { action: mockButtonAction, label: 'button', type: MessageItemType.BUTTON },
+    { label: 'link', type: MessageItemType.LINK, url: 'https://example.org' },
+  ]
+
+  beforeEach(() => {
+    jest.clearAllMocks()
+  })
+
+  it('should do nothing if itemLabel is undefined', async () => {
+    const handleItem = handleMessageItems(mockItems)
+    await handleItem(undefined)
+    expect(mockButtonAction).not.toHaveBeenCalled()
+  })
+
+  it('should throw an error if no item matches the itemLabel', async () => {
+    const handleItem = handleMessageItems(mockItems)
+    await expect(handleItem('unknown label')).rejects.toThrowError()
+  })
+
+  it('should execute the action if the item type is BUTTON', async () => {
+    const handleItem = handleMessageItems(mockItems)
+    await handleItem('button')
+    expect(mockButtonAction).toHaveBeenCalled()
+  })
+
+  it('should open an external link if the item type is LINK', async () => {
+    const handleItem = handleMessageItems(mockItems)
+    await handleItem('link')
+    expect(Uri.parse).toHaveBeenCalledWith('https://example.org')
+    expect(env.openExternal).toHaveBeenCalledWith('https://example.org')
+  })
+
+  it('should throw an error if the item type is unknown', async () => {
+    const handleItem = handleMessageItems([...mockItems, { label: 'unknown', type: 'UNKNOWN' } as any])
+    await expect(handleItem('unknown')).rejects.toThrowError()
+  })
+})

src/helpers/__tests__/isEmpty.test.ts

@@ -0,0 +1,15 @@
+import { isEmpty } from '../isEmpty'
+
+describe('isEmpty', () => {
+  it('should return true if the value is an empty string', () => {
+    expect(isEmpty('')).toBe(true)
+  })
+
+  it('should return true if the value is a string with spaces', () => {
+    expect(isEmpty('   ')).toBe(true)
+  })
+
+  it('should return false if the value is a non-empty string', () => {
+    expect(isEmpty('hello')).toBe(false)
+  })
+})

src/helpers/handleMessageItems.ts

@@ -0,0 +1,30 @@
+import { Uri, env } from 'vscode'
+
+import { InternalError } from '../libs/InternalError'
+import { MessageItemType, type MessageButton, type MessageLink } from '../types'
+
+export function handleMessageItems(items: Array<MessageButton | MessageLink>) {
+  return async function handleMessageItem(itemLabel: string | undefined) {
+    if (!itemLabel) {
+      return
+    }
+
+    const item = items.find(({ label }) => label === itemLabel)
+    if (!item) {
+      throw new InternalError(`This \`item\` does not exist: "${itemLabel}".`)
+    }
+
+    switch (item.type) {
+      case MessageItemType.BUTTON:
+        await item.action()
+        break
+
+      case MessageItemType.LINK:
+        await env.openExternal(Uri.parse(item.url))
+        break
+
+      default:
+        throw new InternalError(`Unknown \`MessageItemType\`: "${(item as any).type}".`)
+    }
+  }
+}

src/helpers/isEmpty.ts

@@ -0,0 +1,9 @@
+import { isEmpty as ramdaIsEmpty } from 'ramda'
+
+export function isEmpty(value: any): boolean {
+  if (typeof value === 'string') {
+    return value.trim() === ''
+  }
+
+  return ramdaIsEmpty(value)
+}