Workflow Examples

Real-world examples demonstrating how to use the Lovelace Neovim extension for common development tasks.

First-Time Setup
Basic Task Workflows
Refactoring Workflows
Code Quality Workflows
Bug Fixing Workflows
Batch Operations
Multi-Project Workflows
Advanced Automation

First-Time Setup

Complete setup flow for new users.

Example: Initial Configuration

vim

" 1. Check extension installation
:LovelaceHealth

" Output:
" ## Daemon Connection
" ✓ Socket found
" ✓ Connection successful
"
" ## Authentication
" ✗ Not authenticated
" ℹ Run :LovelaceAuth to authenticate

" 2. Authenticate with device flow
:LovelaceAuth

" Device flow appears:
" Visit: https://uselovelace.com/device
" Code: ABCD-EFGH

" 3. Press 'c' to copy code
c

" 4. Press 'o' to open browser
o

" 5. Paste code in browser and authorize
" (Browser window opens automatically)

" 6. Wait for confirmation
" ✓ Authentication successful! Welcome to Lovelace.

" 7. Verify setup
:LovelaceHealth

" ## Authentication
" ✓ Authenticated as: user@example.com
" ✓ Session active

" 8. Check session and workspace
:LovelaceSession

" ## Current Workspace
" - Name: my-project
" - Path: /Users/user/Projects/my-project

" 9. Ready to submit first task!

Outcome: Extension fully configured and ready to use

Basic Task Workflows

Simple, common tasks for everyday development.

Example 1: Add Type Annotations

Goal: Add TypeScript types to a JavaScript function

vim

" 1. Open file
:e src/utils/helpers.js

" 2. Navigate to function
/function calculateTotal

" 3. Select function (visual mode)
V}

" Selection:
" function calculateTotal(items) {
"   return items.reduce((sum, item) => sum + item.price, 0);
" }

" 4. Submit task
:LovelaceTask

" Prompt appears:
" Task description:

" 5. Enter description
Add TypeScript type annotations: items should be Item[], return type should be number

" 6. Press Enter to submit
<CR>

" Task submitted (task_abc123) - Status: queued

" 7. Wait for completion notification
" [Task abc123] Completed: 1 file changed

" 8. Review results
:LovelaceTaskStatus task_abc123

" ## Results
" ✓ Task completed successfully
"
" ### Files Changed
" - src/utils/helpers.ts (renamed from .js, types added)
"
" ### Summary
" Added TypeScript type annotations:
" - Parameter 'items' typed as Item[]
" - Return type annotated as number
" - Function signature now type-safe

Outcome: Function has proper TypeScript types

Example 2: Add Error Handling

Goal: Add try-catch to async function

vim

" 1. Open file with async function
:e src/api/users.ts

" 2. Find function without error handling
/async function fetchUser

" 3. Select function body
V}

" 4. Submit task
:LovelaceTask

" 5. Description
Add proper error handling with try-catch. Log errors using logger.
Return Result type instead of throwing.

" Task submitted (task_def456) - Status: queued

" 6. Monitor progress
:LovelaceTaskStatus task_def456

" [14:30:05] Started: Analyzing function...
" [14:30:30] Progress: Adding error handling...
" [14:31:00] Completed: 1 file changed

" 7. Review changes
:LovelaceTaskStatus task_def456

" Shows before/after diff with try-catch added

Outcome: Function has proper error handling with Result types

Example 3: Add Documentation

Goal: Add JSDoc comments to function

vim

" 1. Navigate to undocumented function
:e src/auth/login.ts
/export function validatePassword

" 2. Select function signature and body
V}

" 3. Submit documentation task
:LovelaceTask

" 4. Description
Add comprehensive JSDoc comments explaining parameters,
return value, usage examples, and edge cases.

" 5. Wait for completion
" [Task ghi789] Completed: 1 file changed

" 6. Review added documentation
:LovelaceTaskStatus task_ghi789

Outcome: Function has complete JSDoc documentation

Refactoring Workflows

Complex refactoring tasks across files.

Example 1: Convert Callbacks to Async/Await

Goal: Modernize callback-based code

vim

" 1. Open file with callback code
:e src/legacy/data-loader.js

" 2. Select callback-based function
/function loadUserData
V/^}$

" Selected:
" function loadUserData(userId, callback) {
"   db.query('SELECT * FROM users WHERE id = ?', [userId], (err, result) => {
"     if (err) return callback(err);
"     callback(null, result);
"   });
" }

" 3. Submit refactoring task
:LovelaceTask

" 4. Detailed description
Refactor this callback-based function to use async/await.
Convert to Promise-based approach, add proper error handling
with try-catch, and update all callers to use await.

" Task submitted (task_refactor_001)

" 5. Monitor progress
:LovelaceTaskStatus task_refactor_001

" [14:30:05] Started: Analyzing callback structure...
" [14:30:45] Progress: Converting to async/await...
" [14:31:30] Progress: Updating function callers...
" [14:32:15] Completed: 4 files changed

" 6. Review multi-file changes
:LovelaceTaskStatus task_refactor_001

" ### Files Changed
" - src/legacy/data-loader.js (function converted)
" - src/controllers/user-controller.js (caller updated)
" - src/services/user-service.js (caller updated)
" - tests/data-loader.test.js (tests updated)

Outcome: Callback hell eliminated, modern async/await code

Example 2: Extract Component

Goal: Extract React component from large file

vim

" 1. Open large component file
:e src/components/Dashboard.tsx

" 2. Select code to extract
" (Navigate to UserProfile section)
/const UserProfile
V/^  }$

" 3. Submit extraction task
:LovelaceTask

" 4. Description
Extract this UserProfile section into a separate component file.
Create new file src/components/UserProfile.tsx, move all related
code, add proper imports, and update Dashboard to import it.

" Task submitted (task_extract_001)

" 5. Wait for completion
" [Task extract_001] Completed: 2 files changed

" 6. Review results
:LovelaceTaskStatus task_extract_001

" ### Files Changed
" - src/components/Dashboard.tsx (UserProfile code removed, import added)
" - src/components/UserProfile.tsx (new file created)
"
" ### Summary
" Extracted UserProfile into separate component:
" - Created UserProfile.tsx with proper types
" - Moved all related state and handlers
" - Updated Dashboard to import and use new component
" - Maintained all functionality

Outcome: Large component split into focused, maintainable pieces

Code Quality Workflows

Improve code quality systematically.

Example 1: Add Tests to Untested Module

Goal: Achieve 100% test coverage

vim

" 1. Open module without tests
:e src/utils/validation.ts

" 2. Select entire file
ggVG

" 3. Submit test generation task
:LovelaceTask

" 4. Description
Generate comprehensive test suite for this validation module.
Include unit tests for all functions, edge cases, error scenarios,
and integration tests. Use Vitest and aim for 100% coverage.

" Task submitted (task_test_001)

" 5. Monitor progress
:LovelaceTaskStatus task_test_001

" [14:30:05] Started: Analyzing module functions...
" [14:30:45] Progress: Generating unit tests...
" [14:32:00] Progress: Adding edge case tests...
" [14:33:15] Progress: Creating integration tests...
" [14:34:30] Completed: 1 file changed

" 6. Review generated tests
:LovelaceTaskStatus task_test_001

" ### Files Changed
" - tests/utils/validation.test.ts (new file, 45 tests)
"
" ### Summary
" Created comprehensive test suite:
" - 30 unit tests covering all functions
" - 10 edge case tests (empty inputs, null, undefined)
" - 5 integration tests for validation workflows
" - Estimated coverage: 100%

Outcome: Module has complete test coverage

Example 2: Fix All Linting Errors

Goal: Clean up ESLint violations in file

vim

" 1. Run linter to see errors
:!pnpm lint src/services/api.ts

" Output shows 12 errors:
" - Unused variables
" - Missing return types
" - Inconsistent formatting

" 2. Open file
:e src/services/api.ts

" 3. Select entire file
ggVG

" 4. Submit linting task
:LovelaceTask

" 5. Description
Fix all ESLint errors in this file. Remove unused variables,
add missing TypeScript return types, fix formatting issues,
and ensure all rules pass.

" Task submitted (task_lint_001)

" 6. Wait for completion
" [Task lint_001] Completed: 1 file changed

" 7. Verify all errors fixed
:!pnpm lint src/services/api.ts

" ✓ No linting errors found

Outcome: All ESLint errors resolved

Bug Fixing Workflows

Debug and fix issues efficiently.

Example 1: Fix Reported Bug

Goal: Investigate and fix bug in authentication

vim

" Bug report: "Login fails with 'session undefined' error"

" 1. Open authentication file
:e src/auth/session.ts

" 2. Find session handling code
/function getSession

" 3. Select function
V}

" 4. Submit debugging task
:LovelaceTask

" 5. Description
Fix bug where getSession returns undefined. The function should
handle cases where session cookie doesn't exist. Add null check,
return proper error result, and add defensive programming.

" Task submitted (task_bugfix_001)

" 6. Monitor progress
:LovelaceTaskStatus task_bugfix_001

" [14:30:05] Started: Analyzing session handling...
" [14:30:30] Progress: Identifying null pointer issues...
" [14:31:00] Progress: Adding null checks...
" [14:31:45] Completed: 1 file changed

" 7. Review fix
:LovelaceTaskStatus task_bugfix_001

" ### Files Changed
" - src/auth/session.ts (null checks added)
"
" ### Summary
" Fixed session undefined bug:
" - Added null check for session cookie
" - Return Result type with "session_not_found" error
" - Added defensive check for malformed session data
" - Bug should no longer occur

Outcome: Bug fixed with defensive programming

Example 2: Fix Race Condition

Goal: Eliminate race condition in async code

vim

" Bug: "Sometimes data loads twice"

" 1. Open component with race condition
:e src/components/DataLoader.tsx

" 2. Find useEffect with issue
/useEffect

" 3. Select useEffect block
V}

" 4. Submit fix task
:LovelaceTask

" 5. Description
Fix race condition where data loads twice. Add cleanup function
to useEffect, use AbortController for fetch, and add loading
state guard. Prevent setState on unmounted component.

" Task submitted (task_race_001)

" 6. Review fix when complete
:LovelaceTaskStatus task_race_001

" ### Summary
" Fixed race condition:
" - Added AbortController to cancel in-flight requests
" - Implemented cleanup function in useEffect
" - Added mounted state check before setState
" - Race condition eliminated

Outcome: Race condition eliminated

Batch Operations

Process multiple tasks efficiently.

Example: Batch Type Addition

Goal: Add types to multiple files

vim

" 1. Identify files needing types
:args src/**/*.js

" 2. For each file, submit typing task
:argdo LovelaceTask | next

" Prompts for each file, enter descriptions:
" File 1: "Add TypeScript types to user utilities"
" File 2: "Add TypeScript types to auth helpers"
" File 3: "Add TypeScript types to API client"

" 3. Monitor all tasks
:LovelaceTasks

" ## Running Tasks
" - task_001 | "Add types to user utilities" | Running
" - task_002 | "Add types to auth helpers" | Queued
" - task_003 | "Add types to API client" | Queued

" 4. Wait for all to complete
" Check status periodically
:LovelaceTasks

" ## Completed Tasks
" - task_001 | Completed (2m ago)
" - task_002 | Completed (1m ago)
" - task_003 | Completed (30s ago)

" 5. Review all results
:LovelaceTaskStatus task_001
:LovelaceTaskStatus task_002
:LovelaceTaskStatus task_003

Outcome: Multiple files typed simultaneously

Multi-Project Workflows

Work across multiple projects.

Example: Switch Between Projects

Goal: Work on two projects in same Neovim session

vim

" 1. Start in project A
:cd ~/Projects/project-a
:LovelaceSession

" Workspace: project-a ✓

" 2. Submit task for project A
:e src/components/Header.tsx
V}
:LovelaceTask
" Add responsive breakpoints to Header component

" Task submitted for project-a

" 3. Switch to project B
:cd ~/Projects/project-b
:LovelaceSession

" Workspace: project-b ✓ (updated!)

" 4. Submit task for project B
:e src/api/users.ts
V}
:LovelaceTask
" Add pagination to user listing API

" Task submitted for project-b

" 5. Check all tasks (both projects)
:LovelaceTasks

" ## Running Tasks
" - task_001 | "Add responsive..." | project-a | Running
" - task_002 | "Add pagination..." | project-b | Running

" 6. Tasks execute in correct project context
" Each task modifies files in its respective workspace

Outcome: Work on multiple projects seamlessly

Advanced Automation

Automate repetitive workflows with Lua.

Example 1: Auto-Submit on Save

Goal: Automatically format and check file on save

lua

-- In init.lua or lovelace config

-- Auto-submit linting task on save
vim.api.nvim_create_autocmd("BufWritePost", {
  pattern = "*.ts,*.tsx,*.js,*.jsx",
  callback = function()
    -- Get current file
    local file = vim.fn.expand("%:p")

    -- Submit linting task
    local lovelace = require("lovelace")
    local task_id = lovelace.submit_task({
      description = "Fix linting errors and format code",
      context = {
        file_path = file,
      }
    })

    vim.notify("Lint task submitted: " .. task_id)
  end
})

Usage:

vim

" 1. Edit file
:e src/components/Button.tsx

" 2. Make changes
" (Edit code)

" 3. Save file
:w

" Automatically:
" - Task submitted
" - Linting runs
" - Errors fixed
" - File formatted

Example 2: Custom Task Wrapper

Goal: Create command for common refactoring

lua

-- In init.lua

-- Create custom command for async/await conversion
vim.api.nvim_create_user_command("ConvertToAsync", function()
  local lovelace = require("lovelace.commands")

  -- Get visual selection
  local start_line = vim.fn.line("'<")
  local end_line = vim.fn.line("'>")

  -- Submit pre-configured task
  lovelace.task(
    "Convert this callback-based code to async/await with proper " ..
    "error handling using try-catch and Result types."
  )
end, { range = true })

Usage:

vim

" 1. Select callback code
V}

" 2. Run custom command
:ConvertToAsync

" Task auto-submitted with pre-configured description

Example 3: Batch Test Generation

Goal: Generate tests for all files in directory

lua

-- Generate tests for all files
local function generate_tests_for_directory(dir)
  local files = vim.fn.globpath(dir, "*.ts", 0, 1)

  for _, file in ipairs(files) do
    local lovelace = require("lovelace")

    -- Read file content
    local content = table.concat(
      vim.fn.readfile(file),
      "\n"
    )

    -- Submit test generation task
    lovelace.submit_task({
      description = string.format(
        "Generate comprehensive test suite for %s with 100%% coverage",
        vim.fn.fnamemodify(file, ":t")
      ),
      context = {
        file_path = file,
        buffer_content = content,
      }
    })

    print("Test generation queued for: " .. file)
  end
end

-- Create command
vim.api.nvim_create_user_command("GenerateTestsAll", function()
  generate_tests_for_directory("src/utils")
end, {})

Usage:

vim

:GenerateTestsAll

" Queues test generation for all files
" Monitor with :LovelaceTasks

Tips for Effective Workflows

Write Clear Task Descriptions

✅ Good descriptions:

"Add TypeScript types to User interface: id (string), name (string), email (string), createdAt (Date)"
"Refactor this authentication flow to use async/await instead of callbacks, add try-catch error handling"
"Extract UserProfile section into separate component file at src/components/UserProfile.tsx"

❌ Vague descriptions:

"Fix this"
"Make it better"
"Add types"

Use Visual Mode for Precise Selection

vim

" Select function precisely
/function myFunction
V}

" Select class
/class UserService
V}

" Select specific lines
:10,20  " Lines 10-20

Monitor Long-Running Tasks

vim

" For complex refactoring
:LovelaceTaskStatus task_abc123

" Check periodically
" Watch progress updates appear

Cancel and Retry When Needed

vim

" If task seems stuck
:LovelaceCancel task_abc123

" Resubmit with clearer description
:LovelaceTask

Next Steps

Task Submission Guide - Best practices for effective tasks
Task Monitoring Guide - Track and manage task execution
:LovelaceTask Command - Complete command reference
Configuration Deep Dive - Customize your workflows

Lovelace Developer Portal

Workflow Examples

Table of Contents

First-Time Setup

Example: Initial Configuration

Basic Task Workflows

Example 1: Add Type Annotations

Example 2: Add Error Handling

Example 3: Add Documentation

Refactoring Workflows

Example 1: Convert Callbacks to Async/Await

Example 2: Extract Component

Code Quality Workflows

Example 1: Add Tests to Untested Module

Example 2: Fix All Linting Errors

Bug Fixing Workflows

Example 1: Fix Reported Bug

Example 2: Fix Race Condition

Batch Operations

Example: Batch Type Addition

Multi-Project Workflows

Example: Switch Between Projects

Advanced Automation

Example 1: Auto-Submit on Save

Example 2: Custom Task Wrapper

Example 3: Batch Test Generation

Tips for Effective Workflows

Write Clear Task Descriptions

Use Visual Mode for Precise Selection

Monitor Long-Running Tasks

Cancel and Retry When Needed

Next Steps

Related Documentation

Lovelace Developer Portal