tom_vscode_scripting_api

Dart abstractions for VS Code extension APIs, providing a bridge-agnostic interface for VS Code scripting.

Overview

This package provides a complete Dart API surface for interacting with VS Code extensions. It defines abstract adapter interfaces and concrete socket-based bridge implementations, allowing Dart scripts to control VS Code windows, workspaces, commands, extensions, language models, and chat participants.

Features

• **Window API** — Show messages, quick picks, input boxes, manage editors and terminals, display progress indicators.
• **Workspace API** — Access workspace folders, read/write files, manage configuration, create file watchers.
• **Commands API** — Execute and register VS Code commands.
• **Extensions API** — Query and activate VS Code extensions.
• **Language Model API** — Access AI models (e.g., GitHub Copilot) for chat completions and tool calls.
• **Chat API** — Create chat participants, handle chat requests, stream responses.
• **Bridge Client** — JSON-RPC 2.0 socket-based communication with the VS Code extension host.
• **Script Globals** — Convenient top-level accessors (`vscode`, `window`, `workspace`, `commands`, `extensions`, `lm`, `chat`).

Getting Started

Add the package to your `pubspec.yaml`:

dependencies:
  tom_vscode_scripting_api: ^1.0.0

Usage

Using Script Globals

The simplest way to use the API is through the global accessors:

import 'package:tom_vscode_scripting_api/script_globals.dart';

void main() async {
  // Initialize with a bridge adapter
  VSCode.initialize(adapter);

  // Show a message
  await window.showInformationMessage('Hello from Dart!');

  // Execute a command
  await commands.executeCommand('workbench.action.files.save');

  // Read workspace folders
  final folders = await workspace.getWorkspaceFolders();
  print('Workspace folders: ${folders.map((f) => f.name).join(', ')}');
}

Using the Bridge Client

Connect to VS Code through the socket bridge:

import 'package:tom_vscode_scripting_api/tom_vscode_scripting_api.dart';

void main() async {
  // Create and connect the bridge client
  final client = VSCodeBridgeClient();
  await client.connect();

  // Create the adapter and initialize
  final adapter = VSCodeBridgeAdapter(client);
  VSCode.initialize(adapter);

  // Use the API
  final version = await vscode.getVersion();
  print('VS Code version: $version');

  // Cleanup
  await client.disconnect();
}

Window Operations

// Information, warning, and error messages
await window.showInformationMessage('Info');
await window.showWarningMessage('Warning');
await window.showErrorMessage('Error');

// Quick pick
final choice = await window.showQuickPick(
  ['Option A', 'Option B', 'Option C'],
  placeHolder: 'Choose an option',
);

// Input box
final input = await window.showInputBox(prompt: 'Enter a value');

// Open a file in the editor
await window.showTextDocument('/path/to/file.dart');

Language Model

// Select available models
final models = await lm.selectChatModels(vendor: 'copilot');
if (models.isNotEmpty) {
  final model = models.first;
  final response = await model.sendRequest([
    LanguageModelChatMessage.user('Explain this code'),
  ]);
  print(response);
}

Architecture

The package is structured around three layers:

1. **Adapter interface** (`VSCodeAdapter`) — Abstract request/response contract. 2. **Bridge implementation** (`VSCodeBridgeAdapter`, `VSCodeBridgeClient`) — Socket-based JSON-RPC 2.0 communication with the VS Code extension host. 3. **API namespaces** (`VSCodeWindow`, `VSCodeWorkspace`, etc.) — High-level typed APIs built on the adapter.

License

BSD-3-Clause — see [LICENSE](LICENSE) for details.