Project: Fast, In-Editor CI Workflow for Unity

1. Project Goal

The primary goal is to significantly improve the local developer workflow by enabling key CI tasks to be executed from the command line on an already running Unity Editor instance. This avoids the slow process of shutting down the GUI and relaunching Unity in -batchmode.

The new workflow will be triggered by a -mode=u flag in the existing run-tests.sh script.

2. Core Requirements (The "What")

We need a solution that allows a simple CLI command to trigger the following operations within a running Unity Editor:

1. Refresh Asset Database: Trigger AssetDatabase.Refresh().
2. Regenerate C# Project Files: Trigger the regeneration of .csproj files (equivalent to UnityEditor.SyncVS.SyncSolution()).
3. Run Test Runner: Execute Unity tests (EditMode and/or PlayMode) with specified filters.

Key Characteristics:

• Built, Not Sourced: The core server logic should be custom-built for this project, not reliant on external, unmaintained third-party HTTP server libraries.
• Secure: All communication with the editor must be authenticated (e.g., via a bearer token).
• Performant & Non-Blocking: The editor-side server must operate without blocking the Unity Editor's main thread. All operations, including the server's listening loop and the execution of Unity API calls, should be handled asynchronously where possible, avoiding explicit blocking calls or manual thread management that could impact editor responsiveness.
• Simple CLI Interaction: The CLI interface should be straightforward, using standard tools like curl.
• Harvest Test Results: The CLI script must be able to receive and parse detailed test results (pass/fail status, counts, path to XML report) from the editor.
• Ideally Testable: The core logic should be designed to be testable, adhering to TDD principles where practical.

3. Guiding Principles

All code developed for this project MUST adhere to the following software design and development principles:

• KISS (Keep It Simple, Stupid): Prefer the simplest possible solution that meets the requirements.
• DRY (Don't Repeat Yourself): Avoid code duplication.
• SRP (Single Responsibility Principle): Classes and methods should have one clear responsibility.
• SOLID: Ensure all C# code is written following SOLID principles.

4. High-Level Approach (The "How" - Abstract)

Editor-Side API (C#)

1. In-Editor HTTP Server: Implement a lightweight HTTP server within the Unity Editor using native .NET capabilities (System.Net.HttpListener).
2. Authentication: Integrate a robust authentication mechanism (e.g., bearer token) for all API endpoints.
3. Asynchronous Operations: Design the server to handle requests and execute Unity API calls asynchronously, ensuring the Unity Editor's main thread remains responsive. This will likely involve using Unity's Editor Coroutines or similar asynchronous patterns for dispatching tasks to the main thread without blocking the HTTP listener.
4. API Endpoints: Define clear, RESTful-style API endpoints for each required operation (refresh, regenerate C#, run testrunner).
5. Structured Responses: Ensure API responses are well-structured (e.g., JSON) and provide clear status, messages, and detailed test results where applicable.

CLI-Side Integration (Bash)

1. Script Modification: Enhance the run-tests.sh script to detect a -mode=u flag.
2. HTTP Client: Use curl to send authenticated HTTP requests to the editor-side API.
3. Result Parsing: Parse the JSON responses from the editor API (e.g., using jq) to extract relevant information, especially test results.
4. Exit Status: The script must exit with an appropriate status code (0 for success, 1 for failure) to integrate with CI systems.

5. Definition of Done

• A feature branch feature/fast-editor-workflow has been created and contains all changes.
• The editor-side HTTP server is implemented, secure, and non-blocking.
• The server exposes API endpoints for refreshing assets, regenerating C# project files, and running tests.
• The test-running endpoint accepts filters and returns detailed JSON results.
• The run-tests.sh script correctly uses the -mode=u flag to interact with the editor API.
• The CLI script correctly parses results and exits with appropriate status codes.
• The entire workflow is demonstrably faster and more convenient for local development than batch mode execution.
• All code adheres to the specified guiding principles (KISS, DRY, SRP, SOLID, Testable).