API Reference Overview

Complete reference documentation for all Lokus Plugin APIs. Each plugin receives a PluginContext object that provides access to these APIs.

Quick Start

import { PluginContext } from 'lokus-plugin-sdk';
 
export default class MyPlugin {
  private context: PluginContext;
 
  constructor(context: PluginContext) {
    this.context = context;
  }
 
  async activate(): Promise<void> {
    // Access APIs via context
    this.context.ui.showInformationMessage('Plugin activated!');
    this.context.commands.register('myPlugin.command', {
      name: 'My Command',
      execute: () => { /* ... */ }
    });
  }
 
  async deactivate(): Promise<void> {
    // Cleanup
  }
}

Core APIs

Essential APIs for basic plugin functionality.

EditorAPI

Access: context.editor

Interact with the TipTap editor - add extensions, slash commands, toolbar items, and manipulate editor content.

Key Features:

Add custom TipTap extensions
Register slash commands
Insert and manipulate nodes
Get/replace editor selection
Add keyboard shortcuts
Add toolbar items and context menu items

Example:

await context.editor.addSlashCommand({
  name: 'timestamp',
  description: 'Insert current timestamp',
  execute: async () => {
    const timestamp = new Date().toISOString();
    await context.editor.insertNode('text', {}, timestamp);
  }
});

UIAPI

Access: context.ui

Display notifications, dialogs, and UI components to interact with users.

Key Features:

Show notifications (info, warning, error)
Create dialogs (prompt, confirm, quick pick)
Create output channels for logs
Register panels, tree views, and status bar items
Show progress indicators
Create webview panels

Example:

const result = await context.ui.showConfirm({
  title: 'Confirm Action',
  message: 'Are you sure?'
});
 
if (result) {
  const channel = context.ui.createOutputChannel('My Plugin');
  channel.appendLine('Action confirmed');
  channel.show();
}

CommandsAPI

Access: context.commands

Key Features:

Register commands with metadata
Execute commands programmatically
Add keyboard shortcuts
Show commands in command palette
Organize by categories

Example:

context.commands.register('myPlugin.hello', {
  name: 'Say Hello',
  category: 'My Plugin',
  shortcut: 'Ctrl+Shift+H',
  execute: () => {
    context.ui.showInformationMessage('Hello, World!');
  }
});

WorkspaceAPI

Access: context.workspace

Access workspace information, files, and documents.

Key Features:

Get workspace root path
Access active editor
Listen for file changes
Get workspace configuration
Access open documents

Example:

const rootPath = context.workspace?.rootPath;
const activeEditor = context.workspace?.activeTextEditor;
 
context.workspace?.onDidChangeActiveTextEditor((editor) => {
  context.logger.info(`Editor changed: $\\{editor?.document.fileName\\}`);
});

ConfigurationAPI

Access: context.config

Read and write plugin configuration settings.

Key Features:

Get configuration values
Update configuration
Listen for configuration changes
Plugin-specific settings

Example:

const theme = await context.config.get('theme') ?? 'dark';
await context.config.set('theme', 'light');
 
context.config.onDidChange((e) => {
  if (e.key === 'theme') {
    context.logger.info(`Theme changed to: $\\{e.value\\}`);
  }
});

LanguagesAPI

Access: context.languages

Key Features:

Register completion providers
Add hover information
Implement code actions
Provide formatting
Register linters

Example:

context.languages.registerCompletionProvider('markdown', {
  async provideCompletionItems(document, position) {
    return [
      { label: 'todo', insertText: '- [ ] ' },
      { label: 'done', insertText: '- [x] ' }
    ];
  }
});

Terminal & Tasks

APIs for running commands and managing processes.

TerminalAPI

Access: context.terminal

Create and manage virtual terminals.

Key Features:

Create named terminals
Send commands to terminals
Listen for terminal events
Get active terminal

Example:

const terminal = context.terminal.createTerminal({
  name: 'Build',
  cwd: context.workspace?.rootPath
});
terminal.show();
terminal.sendText('npm run build');

TaskAPI

Access: context.tasks

Key Features:

Register task providers
Execute tasks programmatically
Listen for task events
Get available tasks

Example:

context.tasks.registerTaskProvider('npm', {
  async provideTasks() {
    return [
      { type: 'npm', name: 'build', command: 'npm run build' },
      { type: 'npm', name: 'test', command: 'npm test' }
    ];
  }
});
 
const tasks = await context.tasks.getTasks();
await context.tasks.executeTask(tasks[0]);

Debugging & Themes

DebugAPI

Access: context.debug

Key Features:

Start/stop debugging sessions
Register debug adapters
Provide debug configurations
Listen for debug events

Example:

await context.debug.startDebugging({
  type: 'node',
  name: 'Launch App',
  request: 'launch',
  program: '${workspaceFolder}/index.js'
});

ThemeAPI

Access: context.themes

Key Features:

Register color themes
Get/set active theme
Listen for theme changes
Customize editor colors

Example:

context.themes.registerTheme({
  id: 'my-theme',
  label: 'My Theme',
  uiTheme: 'vs-dark',
  colors: {
    'editor.background': '#1a1a1a',
    'editor.foreground': '#e0e0e0'
  }
});

Storage & Files

APIs for persisting data and accessing files.

StorageAPI

Access: context.storage

Key-value storage for persisting plugin data.

Key Features:

Get/set key-value pairs
Delete values
List all keys
Clear all data
Named databases

Example:

await context.storage.set('settings', { theme: 'dark' });
const settings = await context.storage.get('settings');
 
// Use separate database
const cacheDb = await context.storage.getDatabase('cache');
await cacheDb.set('lastFetch', Date.now());

FilesystemAPI

Access: context.fs

Safe file system access within plugin directory.

Key Features:

Read/write files
Create/delete directories
Copy/move/rename files
Check file existence
Get file metadata
Open file dialogs

Example:

await context.fs.writeFile('config.json', JSON.stringify(config));
const data = await context.fs.readFile('config.json');
const files = await context.fs.readdir('data');

Network & Clipboard

NetworkAPI

Access: context.network

Make HTTP requests (requires network permission).

Key Features:

Fetch API interface
All HTTP methods
Request/response headers
JSON and binary data

Example:

const response = await context.network.fetch('https://api.example.com/data', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ key: 'value' })
});
const data = await response.json();

ClipboardAPI

Access: context.clipboard

Read from and write to the system clipboard.

Key Features:

Copy text to clipboard
Read clipboard content
Clipboard history

Example:

await context.clipboard.writeText('Hello, World!');
 
const items = await context.clipboard.read();
if (items.length > 0) {
  const blob = await items[0].getType('text/plain');
  const text = await blob.text();
}

API Summary Table

API	Access	Permission Required	Purpose
EditorAPI	`context.editor`	None	Editor manipulation
UIAPI	`context.ui`	None	UI components & notifications
CommandsAPI	`context.commands`	None	Command registration
WorkspaceAPI	`context.workspace`	None	Workspace information
ConfigurationAPI	`context.config`	None	Plugin settings
LanguagesAPI	`context.languages`	None	Language features
TerminalAPI	`context.terminal`	None	Terminal management
TaskAPI	`context.tasks`	None	Task automation
DebugAPI	`context.debug`	None	Debugging
ThemeAPI	`context.themes`	None	Theme management
StorageAPI	`context.storage`	None	Data persistence
FilesystemAPI	`context.fs`	None	File operations
NetworkAPI	`context.network`	`network`	HTTP requests
ClipboardAPI	`context.clipboard`	None	Clipboard access

Common Patterns

Command with UI Feedback

context.commands.register('myPlugin.action', {
  name: 'My Action',
  execute: async () => {
    try {
      await context.ui.withProgress(
        { title: 'Processing...' },
        async (progress) => {
          // Do work
          progress.report({ message: 'Step 1...' });
          await doStep1();
          progress.report({ message: 'Step 2...' });
          await doStep2();
        }
      );
      context.ui.showInformationMessage('Success!');
    } catch (error) {
      context.ui.showErrorMessage(`Failed: $\\{error.message\\}`);
    }
  }
});

Persistent Settings

async activate() {
  // Load settings
  const settings = await context.storage.get('settings') ?? defaultSettings;
 
  // Register command to update
  context.commands.register('myPlugin.configure', {
    name: 'Configure',
    execute: async () => {
      const value = await context.ui.showInputBox({
        prompt: 'Enter value',
        value: settings.value
      });
      if (value) {
        settings.value = value;
        await context.storage.set('settings', settings);
      }
    }
  });
}

File Processing

async processFiles() {
  await context.fs.ensureDir('output');
  const files = await context.fs.readdir('input');
 
  for (const file of files) {
    const data = await context.fs.readFile(`input/$\\{file\\}`);
    const processed = await this.process(data);
    await context.fs.writeFile(`output/$\\{file\\}`, processed);
  }
}

API Reference Overview

Quick Start

Core APIs

Terminal & Tasks

Debugging & Themes

Storage & Files

Network & Clipboard

API Summary Table

Common Patterns

Command with UI Feedback

Persistent Settings

File Processing

See Also