Castlight

A Spotlight-like launcher for desktop platforms built with Flutter and clean architecture.

Features

• Applications Tab: Search and launch installed applications on macOS, Windows, and Linux
• Browser Search Tab: Configurable search engines for quick web searches
• Clipboard History Tab: Keep track of your clipboard history with search functionality
• Global Hotkey: Activate with Cmd+Space (macOS) or Alt+Space (Windows/Linux)
• Keyboard Navigation: Full keyboard support with arrow keys, Tab, and Enter
• Clean Architecture: Separation of concerns with Domain, Data, and Presentation layers
• Comprehensive Tests: Unit tests, BLoC tests, and widget tests

Architecture

The project follows Clean Architecture principles:

lib/
├── core/                    # Core utilities and base classes
│   ├── error/              # Error handling (failures, exceptions)
│   ├── usecase/            # Base UseCase interface
│   ├── utils/              # Platform utilities
│   └── di/                 # Dependency injection setup
├── features/               # Feature modules
│   ├── applications/       # Application search and launch
│   ├── browser_search/     # Web search with configurable engines
│   ├── clipboard/          # Clipboard history management
│   └── launcher/           # Main launcher UI
└── main.dart               # Application entry point

Each feature follows the same structure:

• domain/: Entities, repositories (interfaces), and use cases
• data/: Models, data sources, and repository implementations
• presentation/: BLoC (state management) and UI widgets

Getting Started

Prerequisites

• Flutter SDK (3.0.0 or higher)
• Desktop development enabled for your platform:

  flutter config --enable-macos-desktop
  flutter config --enable-windows-desktop
  flutter config --enable-linux-desktop

Installation

1. Install dependencies:

   cd castlight
   flutter pub get

2. Generate mock files for tests:

   flutter pub run build_runner build

3. Run the application:

   # macOS
   flutter run -d macos
   
   # Windows
   flutter run -d windows
   
   # Linux
   flutter run -d linux

Usage

Activating the Launcher

• macOS: Press Cmd + Space
• Windows/Linux: Press Alt + Space

Keyboard Shortcuts

• Esc: Hide the launcher window
• Tab: Switch to next tab
• Shift + Tab: Switch to previous tab
• Arrow Up/Down: Navigate through items
• Enter: Select/launch current item
• Type: Search in the current tab

Tabs

1. Applications Tab

• Automatically discovers installed applications on your system
• Type to search by application name
• Press Enter or click to launch

Platform-specific discovery:

• macOS: Searches /Applications, ~/Applications
• Windows: Searches Program Files and Start Menu
• Linux: Parses .desktop files from XDG directories

2. Browser Search Tab

• Comes with pre-configured search engines (Google, DuckDuckGo, Bing)
• Add custom search engines with {query} placeholder
• Type your query and select a search engine to open in browser

Example custom search engine:

• Name: GitHub
• URL Template: https://github.com/search?q={query}

3. Clipboard History Tab

• Automatically tracks clipboard changes
• Maintains history of up to 100 items
• Search through history
• Click to copy item back to clipboard

Running Tests

Run all tests:

flutter test

Run tests with coverage:

flutter test --coverage

Run specific test file:

flutter test test/features/applications/domain/usecases/get_applications_test.dart

Project Structure

Core Layer

• Failures: Abstract error handling with specific failure types
• Exceptions: Concrete exceptions for different error scenarios
• UseCase: Base interface for all use cases following Single Responsibility Principle
• Dependency Injection: GetIt service locator for managing dependencies

Features

Applications Feature

Domain Layer:

• Application entity: Represents an installed application
• ApplicationRepository: Contract for application operations
• Use cases: GetApplications, SearchApplications, LaunchApplication

Data Layer:

• PlatformApplicationDataSource: Platform-specific app discovery
• ApplicationLocalDataSource: Caching layer
• ApplicationRepositoryImpl: Repository implementation

Presentation Layer:

• ApplicationBloc: State management with events and states
• UI widgets: ApplicationTab, ApplicationItem

Browser Search Feature

Domain Layer:

• SearchEngine entity: Configurable search engine
• Use cases: GetSearchEngines, AddSearchEngine, PerformSearch

Data Layer:

• SearchLocalDataSource: Persistent storage for custom engines
• Default engines included

Presentation Layer:

• SearchBloc: Manages search engine state
• UI widgets: BrowserSearchTab, SearchEngineItem

Clipboard Feature

Domain Layer:

• ClipboardEntry entity: Clipboard item with timestamp and type
• Use cases: GetClipboardHistory, SearchClipboardHistory, CopyToClipboard

Data Layer:

• ClipboardWatcherDataSource: Monitors clipboard changes
• ClipboardLocalDataSource: Persists history

Presentation Layer:

• ClipboardBloc: Manages clipboard state with real-time updates
• UI widgets: ClipboardTab, ClipboardItem

Dependencies

Production Dependencies

• flutter_bloc: State management
• equatable: Value equality
• dartz: Functional programming (Either type)
• get_it: Dependency injection
• hotkey_manager: Global hotkey registration
• window_manager: Window control
• clipboard_watcher: Clipboard monitoring
• shared_preferences: Local storage
• url_launcher: Open URLs in browser
• intl: Date formatting

Development Dependencies

• mockito: Mocking for tests
• bloc_test: BLoC testing utilities
• build_runner: Code generation
• flutter_test: Testing framework
• flutter_lints: Linting rules

Contributing

This project follows clean architecture principles. When adding new features:

1. Start with the domain layer (entities, repository interfaces, use cases)
2. Implement the data layer (models, data sources, repository implementation)
3. Build the presentation layer (BLoC, UI widgets)
4. Write comprehensive tests for each layer

License

This project is open source and available under the MIT License.

Acknowledgments

• Inspired by macOS Spotlight
• Built with Flutter for cross-platform desktop support
• Uses clean architecture principles for maintainability and testability