Skip to content

README.md

Latest commit

 

History

History
318 lines (245 loc) · 8.14 KB

README.md

File metadata and controls

318 lines (245 loc) · 8.14 KB
Raw

Thea Code Developer Guide

Status: Published Last Updated: 2025-08-10 Category: Developer Guide

Overview

This guide provides comprehensive documentation for developers contributing to Thea Code or extending its functionality.

Table of Contents

Getting Started

Architecture

API Reference

Testing

Migration

Development Setup

Prerequisites

  • Node.js 18+ and npm 9+
  • VSCode 1.85.0+
  • Git
  • Docker (for benchmarks)

Installation

  1. Clone the repository
git clone https://github.com/SolaceHarmony/Thea-Code.git
cd Thea-Code
  1. Install dependencies
npm install
  1. Build the extension
npm run build
  1. Run in development mode
npm run watch
  1. Launch VSCode with extension Press F5 in VSCode or:
code --extensionDevelopmentPath=.

Development Workflow

  1. Create a feature branch
git checkout -b feature/your-feature
  1. Make changes and test
npm run test
npm run lint
  1. Build and verify
npm run build
npm run package
  1. Submit pull request
  • Follow PR template
  • Ensure tests pass
  • Update documentation

Project Structure

Thea-Code/
├── src/                    # Source code
│   ├── api/               # API providers and handlers
│   ├── core/              # Core functionality
│   ├── services/          # Service layer (MCP, browser, etc.)
│   ├── integrations/      # VSCode integrations
│   ├── shared/            # Shared utilities
│   └── extension.ts       # Extension entry point
├── webview-ui/            # React webview application
│   ├── src/
│   │   ├── components/    # UI components
│   │   ├── context/       # React context
│   │   └── App.tsx        # Main app component
├── test/                  # Test infrastructure
│   ├── generic-provider-mock/
│   ├── mcp-mock-server/
│   └── openai-mock/
├── docs/                  # Documentation
├── benchmark/             # Performance benchmarks
└── package.json          # Project configuration

Key Components

API Layer (src/api/)

  • BaseProvider - Abstract provider class
  • Provider implementations - Anthropic, OpenAI, Ollama, etc.
  • Transform utilities - Message format conversion

Core System (src/core/)

  • TheaTask - Task management
  • Tool system - Tool definitions and execution
  • Prompt system - System prompts and instructions
  • Configuration - Settings and mode management

Services (src/services/)

  • MCP - Model Context Protocol implementation
  • Browser - Browser automation
  • Terminal - Terminal integration
  • Checkpoints - State management

UI Layer (webview-ui/)

  • React components - Chat, settings, history
  • State management - Extension state context
  • Communication - Message passing with extension

Development Guidelines

Code Style

  • TypeScript - Use TypeScript for all new code
  • ESLint - Follow project ESLint configuration
  • Prettier - Auto-format with Prettier
  • Naming - Use descriptive, consistent naming

Best Practices

  1. Type Safety
// ✅ Good - Explicit types
interface ToolResult {
  success: boolean;
  output?: string;
  error?: Error;
}

// ❌ Bad - Any type
function processTool(result: any) { }
  1. Error Handling
// ✅ Good - Proper error handling
try {
  const result = await riskyOperation();
  return { success: true, data: result };
} catch (error) {
  logger.error('Operation failed', error);
  return { success: false, error };
}
  1. Async/Await
// ✅ Good - Clean async/await
const data = await fetchData();
const processed = await processData(data);

// ❌ Bad - Callback hell
fetchData((data) => {
  processData(data, (processed) => {
    // ...
  });
});

Testing Requirements

  • Unit tests for all utilities and pure functions
  • Integration tests for API providers
  • E2E tests for critical user flows
  • Minimum 80% code coverage

Documentation Requirements

  • JSDoc comments for public APIs
  • README files for new features
  • Update existing docs when changing behavior
  • Include examples in documentation

Common Development Tasks

Adding a New Provider

  1. Create provider class extending BaseProvider
  2. Implement required methods
  3. Add tests in __tests__ directory
  4. Update provider factory
  5. Document in user guide

See Provider Implementation Guide

Adding a New Tool

  1. Define tool in src/core/tools/
  2. Add tool schema
  3. Implement tool handler
  4. Register in tool system
  5. Add tests

See Tool Implementation Guide

Modifying the UI

  1. Edit components in webview-ui/src/components/
  2. Update styles if needed
  3. Test in different themes
  4. Ensure accessibility

See UI Development Guide

Debugging

Extension Debugging

  1. Set breakpoints in VSCode
  2. Press F5 to launch debug session
  3. Use Debug Console for output
  4. Check Extension Host logs

Webview Debugging

  1. Open Developer Tools: Ctrl/Cmd + Shift + P → "Developer: Toggle Developer Tools"
  2. Navigate to Console tab
  3. Use React DevTools if installed

Common Issues

  • Module not found - Run npm install
  • Build errors - Check TypeScript errors with npm run typecheck
  • Test failures - Run specific test with npm test -- [test-name]
  • Port conflicts - Check for running servers

Release Process

  1. Version bump
npm version patch|minor|major
  1. Update CHANGELOG.md
  • Add version section
  • List changes
  • Credit contributors
  1. Create release PR
  • Follow PR template
  • Ensure CI passes
  1. Publish
npm run package
vsce publish

Resources

Internal Documentation

External Resources

Community

Support

For development questions:

  1. Check this guide and related documentation
  2. Search existing GitHub Issues
  3. Ask in the Discord #development channel

Changelog:

  • 2025-08-10: Initial comprehensive developer guide