[2026-04-28] Add apple-browsers .cursor rules (43 files) + executor v2 context
This commit is contained in:
Alexey Martemyanov
@@ -0,0 +1,344 @@
|
||||
---
|
||||
source: ~/DuckDuckGo/apple-browsers.git/main/.cursor/rules/project-structure.mdc
|
||||
confidence: 0.9
|
||||
namespace: work
|
||||
last_synced: 2026-04-28
|
||||
alwaysApply: false
|
||||
---
|
||||
|
||||
# Project Structure & Organization
|
||||
|
||||
## Workspace Structure
|
||||
|
||||
### Root Level
|
||||
```
|
||||
DuckDuckGo.xcworkspace/ # Main workspace (ALWAYS open this)
|
||||
├── iOS/ # iOS app target
|
||||
├── macOS/ # macOS app target
|
||||
├── SharedPackages/ # Cross-platform Swift packages
|
||||
├── fastlane/ # CI/CD automation
|
||||
└── README.md # Main project documentation
|
||||
```
|
||||
|
||||
### iOS App Structure
|
||||
```
|
||||
iOS/
|
||||
├── DuckDuckGo/ # Main iOS app
|
||||
│ ├── AppDelegate.swift # App lifecycle
|
||||
│ ├── MainViewController.swift # Primary browser interface
|
||||
│ ├── BrowserTab.swift # Tab state and WebKit integration
|
||||
│ ├── AIChat/ # AI chat integration
|
||||
│ ├── AppLifecycle/ # App lifecycle management
|
||||
│ ├── Autofill/ # Form autofill features
|
||||
│ ├── Bookmarks/ # Bookmark management
|
||||
│ ├── BrowsingMenu/ # Browser menu UI
|
||||
│ ├── Configuration/ # App configuration
|
||||
│ ├── DataImport/ # Data import utilities
|
||||
│ ├── HealthKitReporting/ # Health data reporting
|
||||
│ ├── MainWindow/ # Main window controllers
|
||||
│ ├── Subscription/ # Premium features
|
||||
│ ├── SyncPrompt/ # Sync feature prompts
|
||||
│ ├── TabSwitcher/ # Tab switching UI
|
||||
│ └── WebView/ # Web view management
|
||||
├── Core/ # iOS-specific shared utilities
|
||||
├── AutofillCredentialProvider/ # Password autofill extension
|
||||
├── PacketTunnelProvider/ # VPN network extension
|
||||
├── OpenAction/ # Share sheet integration
|
||||
├── Widgets/ # Home screen widgets
|
||||
└── Configuration/ # Build configurations
|
||||
```
|
||||
|
||||
### macOS App Structure
|
||||
```
|
||||
macOS/
|
||||
├── DuckDuckGo/ # Main macOS app
|
||||
│ ├── AppDelegate.swift # App lifecycle
|
||||
│ ├── MainWindow.swift # Primary window controller
|
||||
│ ├── BrowserTabViewController.swift # Web view management
|
||||
│ ├── AIChat/ # AI chat integration
|
||||
│ ├── Autofill/ # Form autofill features
|
||||
│ ├── Bookmarks/ # Bookmark management UI
|
||||
│ ├── Downloads/ # Download handling
|
||||
│ ├── NavigationBar/ # URL bar and navigation
|
||||
│ ├── NetworkProtection/ # VPN integration
|
||||
│ ├── Preferences/ # Settings and preferences
|
||||
│ ├── Subscription/ # Premium features
|
||||
│ ├── SyncPrompt/ # Sync feature prompts
|
||||
│ ├── TabBar/ # Tab management UI
|
||||
│ └── WebView/ # Web view management
|
||||
├── DuckDuckGoVPN/ # Standalone VPN app
|
||||
├── NetworkProtectionSystemExtension/ # System-level VPN
|
||||
├── DuckDuckGoDBPBackgroundAgent/ # Data Broker Protection
|
||||
├── DuckDuckGoNotifications/ # System notifications
|
||||
└── Configuration/ # Build configurations
|
||||
```
|
||||
|
||||
## Dependencies and Packages
|
||||
|
||||
### Primary Dependency: BrowserServicesKit
|
||||
```swift
|
||||
// ✅ CORRECT - Always use BrowserServicesKit for shared functionality
|
||||
import BrowserServicesKit
|
||||
|
||||
// Features provided by BrowserServicesKit:
|
||||
// - Content blocking and privacy protection
|
||||
// - Bookmarks and history management
|
||||
// - Secure credential storage
|
||||
// - Autofill functionality
|
||||
// - Navigation handling
|
||||
// - User script injection
|
||||
// - Privacy configuration
|
||||
// - Sync functionality
|
||||
```
|
||||
|
||||
### Shared Packages
|
||||
```
|
||||
SharedPackages/
|
||||
├── AIChat/ # AI chat functionality
|
||||
├── BrowserServicesKit/ # Core browser services
|
||||
├── DataBrokerProtectionCore/ # Data broker protection
|
||||
├── DesignResourcesKitIcons/ # Shared icon resources
|
||||
├── Onboarding/ # User onboarding experience
|
||||
├── UIComponents/ # Reusable UI components
|
||||
└── VPN/ # VPN functionality
|
||||
```
|
||||
|
||||
### Package Dependencies
|
||||
```swift
|
||||
// ✅ CORRECT - Use shared packages for cross-platform features
|
||||
import DesignResourcesKitIcons
|
||||
import UIComponents
|
||||
import BrowserServicesKit
|
||||
|
||||
// ❌ INCORRECT - Don't duplicate functionality across platforms
|
||||
// Keep platform-specific code in iOS/ and macOS/ directories only
|
||||
```
|
||||
|
||||
## Build Configuration
|
||||
|
||||
### Xcode Workspace Setup
|
||||
```swift
|
||||
// ✅ CORRECT - Always open workspace, not individual projects
|
||||
// Open: DuckDuckGo.xcworkspace
|
||||
// Don't open: iOS/DuckDuckGo-iOS.xcodeproj or macOS/DuckDuckGo-macOS.xcodeproj
|
||||
```
|
||||
|
||||
### Build Requirements
|
||||
```
|
||||
iOS:
|
||||
- Xcode 15.0 or later
|
||||
- Swift 5.9 or later
|
||||
- iOS 15.0+ deployment target
|
||||
- Valid Apple Developer account
|
||||
- Provisioning profiles for extensions
|
||||
|
||||
macOS:
|
||||
- Xcode 15.0 or later
|
||||
- Swift 5.9 or later
|
||||
- macOS 11.4+ deployment target
|
||||
- Developer ID certificate (for notarization)
|
||||
- System extension entitlements
|
||||
```
|
||||
|
||||
### Configuration Files
|
||||
```
|
||||
iOS/Configuration/
|
||||
├── Configuration.xcconfig # Base configuration
|
||||
├── Configuration-Alpha.xcconfig # Alpha build settings
|
||||
├── Configuration-Debug.xcconfig # Debug build settings
|
||||
└── BuildNumber.xcconfig # Build number management
|
||||
|
||||
macOS/Configuration/
|
||||
├── Base.xcconfig # Base configuration
|
||||
├── Debug.xcconfig # Debug build settings
|
||||
├── Release.xcconfig # Release build settings
|
||||
└── AppStore.xcconfig # App Store specific
|
||||
```
|
||||
|
||||
## Development Setup
|
||||
|
||||
### Initial Setup
|
||||
```bash
|
||||
# ✅ CORRECT - Development setup steps
|
||||
# 1. Open workspace at root level
|
||||
open DuckDuckGo.xcworkspace
|
||||
|
||||
# 2. Install Ruby dependencies (for Fastlane)
|
||||
bundle install
|
||||
|
||||
# 3. Ensure all certificates and provisioning profiles are installed
|
||||
# 4. SwiftLint is enforced - run before committing
|
||||
```
|
||||
|
||||
### Key Technologies
|
||||
```swift
|
||||
// iOS Stack
|
||||
// - Language: Swift 5.9+
|
||||
// - UI: UIKit with SwiftUI components
|
||||
// - Architecture: MVVM with AppDependencyProvider
|
||||
// - Web Engine: WebKit with privacy enhancements
|
||||
|
||||
// macOS Stack
|
||||
// - Language: Swift 5.9+
|
||||
// - UI: AppKit with SwiftUI components
|
||||
// - Architecture: MVVM with Combine
|
||||
// - Web Engine: WebKit with privacy enhancements
|
||||
// - System Integration: Native macOS features
|
||||
```
|
||||
|
||||
## App Extensions and System Integration
|
||||
|
||||
### iOS Extensions
|
||||
```swift
|
||||
// ✅ CORRECT - iOS extension organization
|
||||
// AutofillCredentialProvider/ - Password autofill
|
||||
// PacketTunnelProvider/ - VPN network extension
|
||||
// OpenAction/ - Share sheet integration
|
||||
// Widgets/ - Home screen widgets
|
||||
```
|
||||
|
||||
### macOS Extensions
|
||||
```swift
|
||||
// ✅ CORRECT - macOS extension organization
|
||||
// NetworkProtectionSystemExtension/ - System-level VPN
|
||||
// DuckDuckGoDBPBackgroundAgent/ - Background data protection
|
||||
// DuckDuckGoNotifications/ - System notifications
|
||||
// VPNProxyExtension/ - VPN proxy functionality
|
||||
```
|
||||
|
||||
## Testing Structure
|
||||
|
||||
### iOS Testing
|
||||
```
|
||||
iOS/
|
||||
├── DuckDuckGoTests/ # Unit tests
|
||||
├── IntegrationTests/ # Integration tests
|
||||
├── PerformanceTests/ # Performance benchmarks
|
||||
├── UITests/ # UI automation tests
|
||||
├── SharedTestUtils/ # Shared test utilities
|
||||
└── WebViewUnitTests/ # WebKit-specific tests
|
||||
```
|
||||
|
||||
### macOS Testing
|
||||
```
|
||||
macOS/
|
||||
├── UnitTests/ # Unit test suite
|
||||
├── IntegrationTests/ # Integration testing
|
||||
├── UITests/ # UI automation tests
|
||||
└── SyncE2EUITests/ # End-to-end sync tests
|
||||
```
|
||||
|
||||
## Important Files and Entry Points
|
||||
|
||||
### iOS Key Files
|
||||
```swift
|
||||
// Core Application Files
|
||||
AppDelegate.swift # App lifecycle and initialization
|
||||
MainViewController.swift # Primary browser interface
|
||||
BrowserTab.swift # Tab state management
|
||||
TabsBarViewController.swift # Tab bar UI (iPad)
|
||||
BookmarksViewController.swift # Bookmarks management
|
||||
PrivacyDashboardViewController.swift # Privacy protection UI
|
||||
```
|
||||
|
||||
### macOS Key Files
|
||||
```swift
|
||||
// Core Application Files
|
||||
AppDelegate.swift # App lifecycle management
|
||||
MainWindow.swift # Primary window controller
|
||||
BrowserTabViewController.swift # Web view management
|
||||
NavigationBarViewController.swift # URL bar and controls
|
||||
PreferencesViewController.swift # Settings interface
|
||||
BookmarksBarViewController.swift # Bookmarks toolbar
|
||||
```
|
||||
|
||||
## Common Development Tasks
|
||||
|
||||
### Running the Apps
|
||||
```swift
|
||||
// ✅ CORRECT - Running applications
|
||||
// iOS: Select "iOS Browser" scheme and simulator/device
|
||||
// macOS: Select "DuckDuckGo" scheme and click Run
|
||||
```
|
||||
|
||||
### Adding New Features
|
||||
```swift
|
||||
// ✅ CORRECT - Feature development flow
|
||||
// 1. Determine if feature belongs in:
|
||||
// - BrowserServicesKit (shared functionality)
|
||||
// - Platform-specific code (iOS/ or macOS/)
|
||||
// 2. Use appropriate dependency injection patterns
|
||||
// 3. Follow existing architecture patterns
|
||||
// 4. Write comprehensive tests
|
||||
```
|
||||
|
||||
### Debugging and Testing
|
||||
```swift
|
||||
// ✅ CORRECT - Testing and debugging
|
||||
// - Run tests: Cmd+U or Test navigator
|
||||
// - Use Safari Web Inspector for web content debugging
|
||||
// - Enable verbose logging in Debug builds
|
||||
// - Use Instruments for performance profiling
|
||||
```
|
||||
|
||||
## Build Schemes and Configurations
|
||||
|
||||
### iOS Build Schemes
|
||||
```
|
||||
- DuckDuckGo (iOS) - Main app
|
||||
- iOS Browser - Browser-specific build
|
||||
- Alpha - Alpha testing build
|
||||
- Debug - Development build
|
||||
```
|
||||
|
||||
### macOS Build Schemes
|
||||
```
|
||||
- DuckDuckGo - Main app
|
||||
- Debug - Development build
|
||||
- Release - Release build
|
||||
- Review - Review build
|
||||
```
|
||||
|
||||
## Platform-Specific Considerations
|
||||
|
||||
### iOS-Specific Features
|
||||
```swift
|
||||
// iOS-specific implementations
|
||||
// - iPad-specific UI adaptations
|
||||
// - iPhone-specific layouts
|
||||
// - iOS system integration
|
||||
// - App Store requirements
|
||||
```
|
||||
|
||||
### macOS-Specific Features
|
||||
```swift
|
||||
// macOS-specific implementations
|
||||
// - Menu bar integration
|
||||
// - Touch Bar support (MacBook Pro)
|
||||
// - Dock integration
|
||||
// - System extensions
|
||||
// - Universal Binary (Intel + Apple Silicon)
|
||||
// - Notarization requirements
|
||||
```
|
||||
|
||||
## Development Best Practices
|
||||
|
||||
### Code Organization
|
||||
```swift
|
||||
// ✅ CORRECT - Follow established patterns
|
||||
// - Use dependency injection via AppDependencyProvider
|
||||
// - Keep platform-specific code in appropriate directories
|
||||
// - Share common functionality through BrowserServicesKit
|
||||
// - Follow MVVM architecture patterns
|
||||
```
|
||||
|
||||
### Performance Considerations
|
||||
```swift
|
||||
// ✅ CORRECT - Performance optimization
|
||||
// - Native Apple Silicon support
|
||||
// - Efficient memory management
|
||||
// - Hardware acceleration
|
||||
// - Optimized content blocking
|
||||
```
|
||||
|
||||
This structure ensures maintainable, testable code while providing comprehensive browser functionality across both iOS and macOS platforms.
|
||||
Reference in New Issue
Block a user