ñ.lat VSCode Extension

A powerful VSCode extension that provides seamless integration with the ñ.lat service for text capture and submission.

TODO

• continue fixing test error
  • npm test -- --testPathPattern=command-manager.test.js --verbose

    Test Suites: 1 failed, 1 passed, 2 total
    Tests:       48 failed, 37 passed, 85 total
    

Quick Start

Open Extension Panel: Ctrl+K Ctrl+H (Windows/Linux) or Cmd+K Cmd+H (macOS)

Overview

The ñ.lat VSCode extension follows a modern, modular architecture designed for maintainability, testability, and extensibility. It provides a clean separation of concerns with dependency injection, centralized error handling, and comprehensive testing infrastructure.

Features

• Authentication Flow: Email-based login with verification codes
• Text Submission: Submit text to ñ.lat service with editor integration
• Session Management: Persistent sessions with automatic timeout handling
• Editor Integration: Insert text at cursor position and retrieve selections
• Configuration Management: Schema-validated configuration with change notifications
• Error Handling: Comprehensive error categorization and recovery strategies
• Debug Support: Conditional debug commands and comprehensive logging
• State Persistence: Maintains state when panel is hidden/shown

Architecture

Core Components

• Extension Manager: Central service registry and lifecycle coordinator
• Webview Manager: Handles webview lifecycle and HTML generation
• Command Manager: VSCode command registration and delegation
• Configuration Manager: Configuration validation and change notifications

Controller Layer

• Session Controller: Authentication flow management
• Text Controller: Text submission and editor integration
• Editor Controller: VSCode editor interactions
• Authentication Controller: API communication for authentication

Service Layer

• Webview Template Service: HTML template generation and management
• State Manager: Centralized application state management

Infrastructure Layer

• Message Router: Type-safe webview message routing
• Error Manager: Centralized error handling and recovery

For detailed architecture information, see the docs/architecture.md file in this extension.

Project Structure

vscode-extension/
├── src/
│   ├── core/                    # Core infrastructure components
│   │   ├── extension-manager.js # Service registry and lifecycle
│   │   ├── webview-manager.js   # Webview lifecycle management
│   │   ├── command-manager.js   # Command registration and delegation
│   │   └── configuration-manager.js # Configuration management
│   ├── controllers/             # Business logic controllers
│   │   ├── session-controller.js    # Authentication flow
│   │   ├── text-controller.js       # Text submission logic
│   │   ├── editor-controller.js     # Editor interactions
│   │   └── auth-controller.js       # API communication
│   ├── services/                # Specialized services
│   │   ├── webview-template-service.js # HTML generation
│   │   └── state-manager.js         # State management
│   ├── infrastructure/          # Cross-cutting concerns
│   │   ├── message-router.js    # Message routing
│   │   └── error-manager.js     # Error handling
│   ├── templates/               # Webview templates
│   │   ├── webview.html        # Main HTML template
│   │   ├── styles.css          # Stylesheet
│   │   └── webview-script.js   # Client-side JavaScript
│   ├── utils/                   # Utility modules
│   └── types/                   # Type definitions
├── tests/                       # Test infrastructure
│   ├── fixtures/               # Test fixtures and mocks
│   ├── unit/                   # Unit tests
│   └── integration/            # Integration tests
├── docs/                       # Documentation
│   └── architecture.md        # Architecture documentation
├── extension.js               # Main extension entry point
└── package.json              # Extension manifest

Development

Prerequisites

• Node.js 16+
• VSCode Extension Development Host
• vsce package for building extensions

Setup

# Install dependencies
npm install

# Install vsce globally (if not already installed)
npm install -g vsce

Build Commands

# Package extension
just build
# or
vsce package --allow-missing-repository

# Clean build artifacts  
just clean
# or
rm -f *.vsix

Testing

# Run unit tests
npm test

# Run integration tests
npm run test:integration

# Run all tests
npm run test:all

# Run tests with coverage
npm run test:coverage

Development Guidelines

1. Code Organization: Follow the established directory structure
2. Error Handling: Use ErrorHandler.createError() for consistent errors
3. Documentation: Add comprehensive JSDoc documentation
4. Testing: Write unit and integration tests for new functionality
5. Performance: Dispose resources properly and avoid memory leaks

Adding New Features

Adding a New Command

1. Add command definition to Command Manager registry
2. Implement handler method in appropriate controller
3. Register message handlers if webview communication needed
4. Add tests for new functionality

Adding a New Service

1. Create service class with initialize/dispose methods
2. Register with Extension Manager including dependencies
3. Implement service interface consistently
4. Add unit tests and integration tests

Adding New Configuration

1. Add schema definition to Configuration Manager
2. Implement custom validator if needed
3. Add change notification handlers
4. Update documentation and tests

Run Tests

• app-cli

  • npx cypress run --config-file cypress.config.cjs --env URL=http://localhost:8000 --spec 'cypress/e2e/app-cli.cy.js'

• Website

  • npm run start-local
  • npx cypress run --config-file cypress.config.cjs --env URL=http://localhost:8000 --spec 'cypress/e2e/home.cy.js'
  • npm run stop-local