Lumivate VS Code Extension

Lumivate is an AI-powered coding education extension for Visual Studio Code. It provides guided course content, real-time code evaluation, and freeform feedback to help students learn to code.

Table of Contents

• For End Users (Installing the Extension)
• For Developers
  • Prerequisites
  • Getting Started
  • Debugging
  • Packaging
  • Project Structure
  • Configuration Settings

For End Users (Installing the Extension)

Step 1 -- Install VS Code

If you don't already have it, download and install Visual Studio Code for your operating system (Windows, Mac, or Linux).

Step 2 -- Install the Lumivate Extension

You will receive a .vsix file (for example, lumivate-extension-1.0.0.vsix). To install it:

1. Open VS Code.
2. Press Ctrl+Shift+P (Windows/Linux) or Cmd+Shift+P (Mac) to open the Command Palette.
3. Type "Install from VSIX" and select Extensions: Install from VSIX....
4. Browse to and select the .vsix file you received.
5. VS Code will install the extension. You may be prompted to reload -- click Reload if asked.

Step 3 -- Configure the Extension

After installation, you need to configure the extension with your Lumivate credentials:

1. Press Ctrl+Shift+P (Windows/Linux) or Cmd+Shift+P (Mac) to open the Command Palette.
2. Type "Settings" and select Preferences: Open Settings (UI).
3. In the search bar at the top, type "lumivate".
4. Fill in each of the settings with the values provided to you by your instructor or administrator:
   • Auth Domain -- the authentication server address
   • Login Auth Client Id -- login client identifier
   • M2M Auth Client Id -- API client identifier
   • M2M Client Secret -- API client secret
   • Auth Api Identifier -- API audience identifier
   • Api Base Url -- the Lumivate API address

Step 4 -- Start Using Lumivate

1. Look at the left sidebar of VS Code. You should see the Lumivate icon (a layered shape).
2. Click it to open the Lumivate panel.
3. Click "Get started" to log in with your Lumivate account.
4. Once logged in, you will see the course dashboard where you can:
   • Navigate courses and sections using the dropdowns and Previous/Next buttons.
   • Write code in the editor and click Evaluate to get AI feedback.
   • Switch to Freeform mode from the menu (hamburger icon at top-left) to get feedback on any code.
   • Adjust difficulty from the Settings menu (1 = easiest, 3 = hardest).

For Developers

Prerequisites

• Node.js >= 18.x (download)
• npm (included with Node.js)
• VS Code >= 1.85.0

No additional system-level dependencies are required. All npm packages are dev-only (TypeScript, ESLint, VS Code type definitions).

Getting Started

# Clone the repository
git clone https://github.com/johncross116/Lumivate.ExtensionVsCode.git
cd Lumivate.ExtensionVsCode

# Install dependencies
npm install

# Compile TypeScript
npm run compile

Debugging

There are two ways to debug the extension:

Option A -- VS Code Extension Development Host (Recommended)

1. Open the Lumivate.ExtensionVsCode folder in VS Code.

2. Create a launch configuration if one doesn't exist. Add the following to .vscode/launch.json:

   {
     "version": "0.2.0",
     "configurations": [
       {
         "name": "Run Extension",
         "type": "extensionHost",
         "request": "launch",
         "args": [
           "--extensionDevelopmentPath=${workspaceFolder}"
         ],
         "outFiles": [
           "${workspaceFolder}/out/**/*.js"
         ],
         "preLaunchTask": "npm: compile"
       }
     ]
   }
   

3. Press F5 to launch a new VS Code window (the "Extension Development Host") with the extension loaded.

4. In the new window, the Lumivate icon will appear in the activity bar. Click it to open the sidebar panel.

5. You can set breakpoints in the TypeScript source files (src/) -- VS Code will hit them in the Development Host.

6. View extension logs in the Output panel (select "Lumivate" from the dropdown).

Option B -- Watch Mode

Run the TypeScript compiler in watch mode so changes recompile automatically:

npm run watch

Then press F5 in VS Code to launch the Extension Development Host. After making code changes, press Ctrl+Shift+F5 to reload the host window.

Debugging Tips

• Output Channel: The extension logs to an output channel called "Lumivate". Open it via View > Output and select "Lumivate" from the dropdown.
• Error Log File: Errors are also written to ~/.lumivate/errors/ErrorLog.txt.
• Webview DevTools: To debug the sidebar webview, open the Command Palette and run Developer: Open Webview Developer Tools.
• Settings Validation: On activation, the extension checks for required settings. If any are missing, a warning notification appears with a link to open settings.

Packaging

To create a .vsix file for distribution:

# Install the packaging tool (one-time)
npm install -g @vscode/vsce

# Compile the extension
npm run compile

# Package it
vsce package

This creates a file like lumivate-extension-1.0.0.vsix in the project root. Share this file with end users for installation.

Note: vsce package runs npm run vscode:prepublish (which runs npm run compile) automatically, so the separate compile step is optional.

Project Structure

Lumivate.ExtensionVsCode/
├── media/
│   ├── icon.svg              # Sidebar icon (SVG)
│   └── main.css              # Webview stylesheet
├── src/
│   ├── config.ts             # Reads lumivate.* settings from VS Code config
│   ├── extension.ts          # Main entry point (activate/deactivate)
│   ├── stateManager.ts       # Centralized state with persistence
│   ├── helpers/
│   │   └── storageHelper.ts  # VS Code globalState wrapper
│   ├── models/
│   │   ├── course.ts         # Course and Module interfaces
│   │   ├── index.ts          # Barrel export
│   │   ├── requests.ts       # API request types
│   │   ├── responses.ts      # API response types
│   │   ├── section.ts        # Section, QuestionType, Direction enums
│   │   ├── setting.ts        # Difficulty setting
│   │   └── student.ts        # Student interface
│   ├── providers/
│   │   ├── authProvider.ts   # Auth0 PKCE login + URI handler
│   │   ├── editorProvider.ts # Read/reset VS Code editor content
│   │   ├── errorHandler.ts   # Multi-destination error logging
│   │   ├── httpProvider.ts   # Authenticated HTTP client with token caching
│   │   └── retryProvider.ts  # Exponential backoff retry logic
│   └── webview/
│       ├── getWebviewContent.ts    # HTML generator for the sidebar panel
│       └── lumivateViewProvider.ts # WebviewViewProvider (all UI logic)
├── out/                       # Compiled JavaScript (generated)
├── package.json               # Extension manifest and scripts
├── tsconfig.json              # TypeScript configuration
└── .eslintrc.json             # ESLint rules

Configuration Settings

All settings are under the lumivate.* namespace in VS Code settings. These must be configured before the extension can function:

API calls authenticate as the logged-in user via the access token issued by Auth0 during login, not via a machine-to-machine client_credentials grant. No client secret is required.