diff --git a/CMakeLists.txt b/CMakeLists.txt index 43729f6..530f626 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -1,23 +1,71 @@ # ============================================================================== -# Wingman VST3 with WebView2 Integration - PRODUCTION READY +# Wingman VST3 Plugin - CMake Build Configuration # ============================================================================== -# This CMakeLists includes: -# - Automatic React UI building -# - Full WebView2 Integration with DELAYLOAD -# - Automatic moduleinfo.json fix (prevents detection issues) -# - Comprehensive post-build verification +# +# PROJECT: Wingman AI Music Production Assistant +# COMPONENT: VST3 Plugin (JUCE + WebView2) +# STATUS: Experimental (loads but UI integration incomplete) +# +# This CMakeLists configures: +# 1. React UI automatic building (from actual ui/vocal-muse-sidecar-main) +# 2. JUCE audio plugin framework integration +# 3. WebView2 embedded browser (Windows only) +# 4. VST3 bundle creation with proper structure +# 5. Post-build fixes (moduleinfo.json, resource copying) +# +# PLATFORMS: +# - Windows: Primary (Visual Studio 2019+, WebView2 SDK required) +# - macOS: Partial (Xcode 13+, WebView2 N/A) +# - Linux: Untested (GCC 9+/Clang 10+) +# +# BUILD INSTRUCTIONS: +# See docs/BUILD_SETUP.md for complete instructions per platform +# +# REQUIREMENTS: +# - CMake 3.22+ +# - Node.js 18+ (for React UI build) +# - JUCE 8.0.9+ (submodule) +# - [Windows] WebView2 SDK 1.0.2210.55 (via NuGet) +# - [Windows] Visual Studio 2019+ with C++ workload +# - [macOS] Xcode 13+ with command line tools +# # ============================================================================== cmake_minimum_required(VERSION 3.22) -project(Wingman VERSION 1.0.0) +project(Wingman VERSION 1.0.0 LANGUAGES CXX) +# ============================================================================== +# Compiler Configuration +# ============================================================================== + +# Require C++17 for modern features (auto, lambdas, std::optional, etc.) set(CMAKE_CXX_STANDARD 17) set(CMAKE_CXX_STANDARD_REQUIRED ON) -# Static runtime +# Use static runtime to avoid DLL dependencies on target systems +# MultiThreaded (Release) or MultiThreadedDebug (Debug) set(CMAKE_MSVC_RUNTIME_LIBRARY "MultiThreaded$<$:Debug>") -# --- Build React UI --- +# ============================================================================== +# React UI Build Step +# ============================================================================== +# +# The plugin embeds a React-based UI using WebView2 (Windows) or native +# web components (macOS/Linux future). This target ensures the UI is built +# before the plugin compiles. +# +# BUILD PROCESS: +# 1. npm install - Install dependencies +# 2. npm run build - Vite builds React app to dist/ +# 3. Post-build copies dist/ to plugin bundle Resources/webui/ +# +# OUTPUT: actual ui/vocal-muse-sidecar-main/dist/ +# - index.html (entry point) +# - assets/*.js (bundled JavaScript) +# - assets/*.css (bundled styles) +# +# ============================================================================== + set(REACT_UI_DIR "${CMAKE_SOURCE_DIR}/actual ui/vocal-muse-sidecar-main") set(REACT_UI_SOURCE_DIR "${REACT_UI_DIR}/dist") @@ -25,24 +73,43 @@ add_custom_target(BuildReactUI ALL COMMAND npm install COMMAND npm run build WORKING_DIRECTORY "${REACT_UI_DIR}" - COMMENT "Building React UI with cache verification..." + COMMENT "Building React UI from source..." + VERBATIM ) -# ===================================================================================== -# ๐Ÿšจ WEBVIEW2 SCHEME HANDLER GUARDRAIL - BUILD VERIFICATION -# ===================================================================================== -# This CMake configuration ensures WEBVIEW2 SCHEME HANDLERs are registered at the correct time. -# -# CRITICAL REQUIREMENT: Scheme handlers MUST be registered BEFORE WebView2 initialization() -# Build Process Order: -# 1. CMake configures build order -# 2. WebView2Handler.cpp scheme registration happens BEFORE WebView2 initialization() -# 3. If this order is violated, the plugin will show "404 resource not found" errors -# -# NEVER modify WebView2Handler.cpp to move scheme registration after WebView2 initialization()! -# ===================================================================================== - -# JUCE +# ============================================================================== +# ๐Ÿšจ CRITICAL IMPLEMENTATION NOTE - WebView2 Scheme Handler Registration +# ============================================================================== +# +# PROBLEM: +# WebView2 scheme handlers (used to serve local files to the embedded browser) +# MUST be registered BEFORE WebView2 initialization. If registered after, +# the plugin will show "404 resource not found" errors for all UI files. +# +# SOLUTION: +# The build system enforces correct build order: +# 1. CMake configures dependencies +# 2. React UI builds (BuildReactUI target) +# 3. C++ compilation happens (includes WebView2Handler.cpp) +# 4. WebView2Handler.cpp registers scheme handler in constructor +# 5. WebView2 initialization happens AFTER handler registration +# +# DO NOT MODIFY: +# - Build order dependencies (add_dependencies below) +# - WebView2Handler.cpp scheme registration timing +# - Initialization sequence in PluginEditor.cpp +# +# IF YOU MODIFY AND BREAK THIS: +# Symptom: Plugin loads but shows blank/white screen +# Fix: Restore proper initialization order +# Debug: Check Ableton Log.txt for "Failed to load resource" errors +# +# This guardrail comment ensures future developers understand the critical +# dependency between scheme handler registration and WebView2 initialization. +# +# ============================================================================== + +# Add JUCE framework (submodule at ./JUCE) add_subdirectory(JUCE juce) # VST3 Plugin Configuration diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..f2ebe7a --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,560 @@ +# Contributing to Wingman + +Thank you for your interest in contributing to Wingman! This document provides guidelines and information for contributors. + +**Current Status**: Project is in alpha development and **not yet accepting external contributions**. This document outlines future contribution guidelines. + +--- + +## ๐Ÿ“‹ Table of Contents + +- [Code of Conduct](#code-of-conduct) +- [Getting Started](#getting-started) +- [Development Workflow](#development-workflow) +- [Coding Standards](#coding-standards) +- [Commit Guidelines](#commit-guidelines) +- [Pull Request Process](#pull-request-process) +- [Testing Requirements](#testing-requirements) +- [Documentation](#documentation) + +--- + +## ๐Ÿ“œ Code of Conduct + +### Our Pledge + +We are committed to providing a welcoming and inclusive environment for all contributors, regardless of: +- Experience level +- Gender identity and expression +- Sexual orientation +- Disability +- Personal appearance +- Body size +- Race, ethnicity, or nationality +- Age +- Religion + +### Expected Behavior + +- **Be Respectful**: Treat all contributors with respect and kindness +- **Be Collaborative**: Work together and help each other +- **Be Professional**: Keep discussions focused on technical matters +- **Be Open-Minded**: Welcome different perspectives and ideas +- **Give Credit**: Acknowledge others' contributions + +### Unacceptable Behavior + +- Harassment, trolling, or personal attacks +- Discriminatory or offensive language +- Publishing others' private information +- Spam or off-topic discussions +- Any conduct that would be inappropriate in a professional setting + +### Enforcement + +Violations will result in warnings, temporary bans, or permanent bans at maintainers' discretion. Report issues to project maintainers. + +--- + +## ๐Ÿš€ Getting Started + +### Prerequisites + +Before contributing, ensure you have: +- [ ] Read the [README.md](README.md) +- [ ] Set up your development environment ([docs/BUILD_SETUP.md](docs/BUILD_SETUP.md)) +- [ ] Built the project successfully +- [ ] Familiarized yourself with the architecture ([CLAUDE.md](CLAUDE.md)) +- [ ] Checked [KNOWN_ISSUES.md](KNOWN_ISSUES.md) and [TODO.md](TODO.md) + +### Finding Something to Work On + +**Not yet available** - Will be added when project reaches stable state. + +Future options: +- Check GitHub Issues labeled `good-first-issue` +- Check [TODO.md](TODO.md) for tasks +- Ask in GitHub Discussions + +--- + +## ๐Ÿ”„ Development Workflow + +### Fork and Clone + +```bash +# Fork the repository on GitHub first + +# Clone your fork +git clone https://github.com/YOUR_USERNAME/wingman.git +cd wingman + +# Add upstream remote +git remote add upstream https://github.com/micahcooley/wingman.git +``` + +### Create a Branch + +```bash +# Update your fork +git checkout main +git pull upstream main + +# Create a feature branch +git checkout -b feature/your-feature-name + +# Or for bug fixes +git checkout -b fix/issue-description +``` + +### Branch Naming Conventions + +| Type | Prefix | Example | +|------|--------|---------| +| New Feature | `feature/` | `feature/add-midi-quantization` | +| Bug Fix | `fix/` | `fix/memory-leak-plugin` | +| Documentation | `docs/` | `docs/update-build-guide` | +| Performance | `perf/` | `perf/optimize-midi-generation` | +| Refactoring | `refactor/` | `refactor/cleanup-services` | +| Testing | `test/` | `test/add-unit-tests` | +| CI/CD | `ci/` | `ci/add-github-actions` | + +### Make Changes + +1. **Write Code**: Follow [Coding Standards](#coding-standards) +2. **Add Tests**: Cover new functionality +3. **Update Docs**: Document changes +4. **Run Linters**: Ensure code quality +5. **Test Locally**: Verify everything works + +```bash +# Run linters +cd wingman-app +npm run lint + +# Run tests (when available) +npm test + +# Build to verify +npm run build +``` + +### Commit Changes + +Follow [Commit Guidelines](#commit-guidelines): + +```bash +git add . +git commit -m "feat: Add MIDI quantization feature" +``` + +### Push to Your Fork + +```bash +git push origin feature/your-feature-name +``` + +### Open Pull Request + +1. Go to your fork on GitHub +2. Click "Compare & pull request" +3. Fill out PR template (when available) +4. Link related issues +5. Wait for review + +--- + +## ๐Ÿ“ Coding Standards + +### General Principles + +- **KISS**: Keep It Simple, Stupid +- **DRY**: Don't Repeat Yourself +- **YAGNI**: You Aren't Gonna Need It +- **SOLID**: Single responsibility, Open/closed, Liskov substitution, Interface segregation, Dependency inversion + +### Language-Specific Guidelines + +#### TypeScript/JavaScript + +**Style Guide**: Airbnb JavaScript Style Guide (with modifications) + +**Key Points**: +- Use TypeScript for all new code +- Prefer `const` over `let`, avoid `var` +- Use arrow functions for callbacks +- Use async/await over promises +- Add JSDoc comments for public APIs +- Use ESLint and Prettier + +**Example**: +```typescript +/** + * Generates MIDI pattern based on user prompt and AI specifications. + * @param prompt - User's natural language request + * @param refinedParams - AI-refined parameters for generation + * @returns Promise resolving to MIDI sequence + * @throws {MagentaError} If generation fails + */ +export async function generateMidiPattern( + prompt: string, + refinedParams: MusicParameters +): Promise { + // Implementation +} +``` + +#### C++ (JUCE Plugin) + +**Style Guide**: JUCE Coding Standards + Google C++ Style Guide + +**Key Points**: +- Use JUCE idioms (MessageManager, AudioProcessor, etc.) +- Follow RAII principles +- Use smart pointers (`std::unique_ptr`, `std::shared_ptr`) +- Avoid raw `new`/`delete` +- Use `const` liberally +- Add Doxygen comments for public APIs + +**Example**: +```cpp +/** + * @brief Handles WebView2 message from React UI + * + * Parses JSON message, validates schema, and dispatches to appropriate handler. + * Thread-safe: Can be called from WebView2 thread. + * + * @param message JSON string from WebView2 + * @throws std::invalid_argument if message format is invalid + */ +void WingmanProcessor::handleWebMessage(const juce::String& message) { + // Implementation +} +``` + +#### Python (Remote Script) + +**Style Guide**: PEP 8 + +**Key Points**: +- Follow PEP 8 strictly +- Use type hints (Python 3.8+) +- Add docstrings (Google style) +- Keep functions small and focused +- Use meaningful variable names + +**Example**: +```python +def launch_clip(track_index: int, scene_index: int, quantization: int = 1) -> bool: + """ + Launches clip at specified track and scene indices. + + Args: + track_index: Zero-based track index in Live set + scene_index: Zero-based scene index + quantization: Launch quantization (0=none, 1=bar, 2=beat, etc.) + + Returns: + True if clip launched successfully, False otherwise + + Raises: + IndexError: If track or scene index out of range + """ + # Implementation +``` + +### Code Organization + +#### File Structure +``` +# TypeScript +src/ + โ”œโ”€โ”€ services/ # Business logic + โ”œโ”€โ”€ components/ # React components + โ”œโ”€โ”€ hooks/ # Custom React hooks + โ”œโ”€โ”€ utils/ # Helper functions + โ””โ”€โ”€ types/ # TypeScript types/interfaces + +# C++ +Source/ + โ”œโ”€โ”€ *.h # Header files + โ”œโ”€โ”€ *.cpp # Implementation files + โ””โ”€โ”€ README.md # Component documentation +``` + +#### Naming Conventions + +| Type | Convention | Example | +|------|-----------|---------| +| **TypeScript** | +| Files | camelCase | `musicPromptRefiner.ts` | +| Classes | PascalCase | `MagentaService` | +| Functions | camelCase | `generateMidiPattern()` | +| Constants | UPPER_SNAKE_CASE | `DEFAULT_TEMPO` | +| Interfaces | PascalCase | `MusicParameters` | +| **C++** | +| Classes | PascalCase | `WingmanProcessor` | +| Methods | camelCase | `processBlock()` | +| Members | camelCase_ | `sampleRate_` | +| Constants | kCamelCase | `kMaxBufferSize` | +| **Python** | +| Files | snake_case | `command_handler.py` | +| Classes | PascalCase | `ObserverManager` | +| Functions | snake_case | `launch_clip()` | +| Constants | UPPER_SNAKE_CASE | `DEFAULT_TEMPO` | + +### Comments + +**When to Comment**: +- โœ… Complex algorithms +- โœ… Non-obvious design decisions +- โœ… Public APIs +- โœ… Workarounds for bugs +- โœ… TODO/FIXME/HACK markers + +**What NOT to Comment**: +- โŒ Obvious code (`i++; // increment i`) +- โŒ Outdated information +- โŒ Code that should be self-explanatory + +**Example**: +```typescript +// โœ… Good: Explains WHY +// Use exponential backoff to avoid rate limiting (max 10 retries) +const delay = Math.min(1000 * Math.pow(2, retries), 30000); + +// โŒ Bad: Explains WHAT (obvious from code) +// Set the delay to 1000 times 2 to the power of retries +const delay = 1000 * Math.pow(2, retries); +``` + +--- + +## ๐Ÿ’ฌ Commit Guidelines + +### Conventional Commits + +We use [Conventional Commits](https://www.conventionalcommits.org/) specification. + +**Format**: +``` +(): + + + +