Add cross-platform VS Code editor adapter for MrBuild LSP proof

Problem Statement

MrBuild now has a real LSP Coordinator and worker architecture, but there is no editor adapter through which a developer can prove that the public LSP works in an actual editor. Worker tests and the existing stdio harness do not show the user-facing path: VS Code activation, server discovery, process startup, editor document synchronization, diagnostics, hover, navigation, workspace control, and visible recovery behavior.

The proof must be cross-platform and reproducible. It must support an editor-driven verification session, permit attaching a .NET debugger to a managed Coordinator process, and leave room for future editor adapters without moving editor-specific behavior into the LSP Coordinator.

Solution

Build a thin VS Code Editor Adapter written in F# and compiled to JavaScript with Fable. Use the pinned source form of ionide-vscode-helpers for VS Code bindings and preserve its existing Paket/Fable/Yarn/Webpack toolchain as an isolated build island for the first proof.

The adapter launches the existing Four-Role Executable over stdio and consumes the public LSP plus Workspace Control Plane. It accepts either a native Coordinator executable or a managed Coordinator DLL; DLL launches use a configurable dotnet executable so the actual managed process can be debugged. Launch configuration remains shell-free and does not accept arbitrary command lines.

The adapter exposes workspace selection, reload, target selection, F# file-mode selection, and workspace-status commands through the VS Code Command Palette. It provides output/status feedback, fails fast with actionable guidance when the server artifact is missing, and does not restore or build implicitly during activation.

Use the existing cross-platform FAKE build pipeline as the source of truth. Add explicitly VS Code-namespaced targets for restore, build, packaging, and local interactive proof. The local proof target launches an isolated VS Code instance with disposable user-data and extensions directories; CI-safe targets build and validate artifacts without requiring a GUI editor.

Use a shared editor-neutral mixed-language fixture. The first editor acceptance flow must demonstrate an intentional diagnostic, hover, F# to C# definition navigation, C# to F# definition navigation, workspace status inspection, and workspace reload through the real Coordinator and actual child workers.

User Stories

1. As a MrBuild developer, I want a VS Code extension written in F# and compiled with Fable, so that the editor proof uses the requested language and runtime model.
2. As a MrBuild developer, I want the extension to use ionide-vscode-helpers for VS Code bindings, so that the adapter follows the Ionide ecosystem rather than inventing bindings.
3. As a repository maintainer, I want the helper source pinned to a known revision, so that builds are reproducible and upstream changes do not silently alter the proof.
4. As a repository maintainer, I want the helper’s Paket/Fable/Yarn/Webpack dependencies isolated from MrBuild’s .NET package graph, so that the first proof does not require an unrelated toolchain migration.
5. As a VS Code user, I want the extension to start the real MrBuild LSP Coordinator over stdio, so that editor behavior proves the production runtime boundary.
6. As a VS Code user, I want the extension to launch a native Coordinator executable, so that normal local development can use the fastest built artifact.
7. As a VS Code user, I want the extension to launch a Coordinator DLL through dotnet, so that I can attach a .NET debugger to the managed process.
8. As a VS Code user, I want to override the Coordinator artifact path, so that I can verify alternate builds and debug configurations.
9. As a VS Code user, I want to override the dotnet executable used for DLL launches, so that SDK selection and debugger setup work across platforms.
10. As a VS Code user, I want server launch configuration to avoid shell parsing, so that paths and arguments behave consistently and do not create arbitrary command execution.
11. As a VS Code user, I want a clear error when the Coordinator artifact is missing, so that I know exactly which prerequisite build to run.
12. As a VS Code user, I want extension activation to avoid implicit restore and build work, so that startup is predictable and does not mutate my workspace unexpectedly.
13. As a VS Code user, I want MrBuild workspace selection available from the Command Palette, so that I can select a solution, traversal project, project subset, or other supported workspace without an editor-specific protocol.
14. As a VS Code user, I want to reload the MrBuild workspace from the Command Palette, so that saved project changes can produce a fresh Project Snapshot.
15. As a VS Code user, I want to select an active target from the Command Palette, so that I can control which target framework supplies interactive results.
16. As a VS Code user, I want to choose the F# file mode for an ambiguous .fsx, so that Script Mode and Project Mode are explicit when both interpretations are plausible.
17. As a VS Code user, I want to inspect Workspace Status from VS Code, so that worker health, selection, active targets, snapshots, and degraded state are visible without reading raw protocol traffic.
18. As a VS Code user, I want diagnostics to appear in the editor, so that I can verify the end-to-end document synchronization and language-worker path.
19. As a VS Code user, I want hover results to appear in the editor, so that I can verify semantic requests through the public LSP.
20. As an F# developer, I want definition navigation from F# to C# source, so that cross-language source navigation is proven at the editor surface.
21. As a C# developer, I want definition navigation from C# to F# source, so that cross-language source navigation is proven in both directions.
22. As a VS Code user, I want workspace reload to be observable through status or output feedback, so that I can distinguish a completed reload from a silent failure.
23. As a debugger, I want a ready-made managed-process attach configuration, so that I can attach to the Coordinator without reconstructing debugger settings.
24. As a verifier, I want a disposable VS Code profile, so that unrelated extensions, settings, and cached workspace state cannot mask failures.
25. As a verifier, I want a deterministic mixed-language fixture, so that the same editor behavior can be reproduced locally and reused by future editor adapters.
26. As a verifier, I want the proof launcher to report the instance, profile, fixture, and process information, so that an editor-driving automation session can connect to and diagnose the correct VS Code instance.
27. As a maintainer, I want CI-safe VS Code build targets, so that extension artifacts can be restored, built, packaged, and validated without launching a GUI.
28. As a maintainer, I want the interactive proof target to be explicitly local-only, so that CI never hangs waiting for an editor or desktop session.
29. As a future editor-integration author, I want the LSP Coordinator to remain editor-neutral, so that another editor can reuse the public protocol and Workspace Control Plane.
30. As a future editor-integration author, I want the shared fixture and acceptance expectations to be editor-neutral, so that a new adapter can prove equivalent behavior without duplicating semantic test projects.

Implementation Decisions

• Build a VS Code Editor Adapter as a separate F# + Fable project. The adapter owns VS Code lifecycle, configuration, process launch, Command Palette registration, output/status presentation, and editor-specific debugging affordances.
• Keep language semantics, project evaluation, worker health, workspace selection, snapshots, and cross-language navigation in the existing LSP Coordinator and public Workspace Control Plane.
• Consume ionide-vscode-helpers as pinned Git source, including its binding project, rather than as a published package or copied source. Preserve the helper’s existing build toolchain initially.
• Use the existing FAKE build pipeline as the only build orchestration source. Add the targets VsCodeRestore, VsCodeBuild, VsCodePackage, and VsCodeProof; do not add a competing standalone F# script build entrypoint.
• Make the first three targets CI-safe and cross-platform through the repository’s existing shell wrappers. Make VsCodeProof local-only and interactive.
• Treat the server configuration as a typed launch descriptor: a native executable path launches directly; a DLL path launches through a configurable dotnet executable. Do not accept arbitrary shell command lines or unrestricted server argument strings in the first slice.
• Infer the default Coordinator artifact from the workspace/repository build output while allowing an explicit path override for alternate builds.
• Fail fast when the inferred or configured artifact does not exist, with an actionable VS Code error and output-channel guidance pointing to the appropriate VS Code build target.
• Use the public LSP over stdio and the existing vscode-languageclient-compatible binding surface. Do not create an editor-only semantic RPC layer.
• Register Command Palette commands for workspace selection, workspace reload, active-target selection, F# file-mode selection, and workspace-status inspection. Map them to the existing public commands and custom requests.
• Include an explicit managed-process debugger attach configuration for the Coordinator.
• Launch proof sessions with disposable VS Code user-data and extensions directories and only the proof adapter enabled.
• Keep the mixed-language acceptance fixture editor-neutral and share it with future editor adapters.
• Preserve the existing End-to-End LSP Harness as the lower-level public protocol/process-boundary test. Add the VS Code proof as the highest seam that verifies editor-visible behavior.

Testing Decisions

• Tests must assert externally visible behavior at the editor boundary, not Fable-generated JavaScript structure or private adapter helper functions.
• The primary test is an editor-driven end-to-end scenario in a real VS Code Extension Development Host using the real Coordinator and actual child workers over stdio.
• The first scenario uses the shared mixed-language fixture and verifies diagnostics, hover, F# to C# definition navigation, C# to F# definition navigation, Workspace Status, and workspace reload.
• Verify both native executable launch and managed DLL launch through dotnet; the managed path must leave an attachable Coordinator process.
• Verify missing-artifact behavior is actionable and does not trigger implicit restore/build.
• Verify the isolated profile prevents unrelated installed extensions and user settings from participating.
• Verify the named VsCodeRestore, VsCodeBuild, and VsCodePackage targets on the supported CI platforms without launching a GUI.
• Verify VsCodeProof locally with a disposable profile and confirm it reports the instance/profile/process information needed for editor-driving automation.
• Reuse the existing End-to-End LSP Harness and LSP runtime tests as prior art for real stdio Coordinator and worker behavior; the VS Code test should add only the editor-adapter and editor-surface assertions.

Out of Scope

• Marketplace or Open VSX publication.
• Supporting editors other than VS Code.
• Moving language semantics or workspace policy into the VS Code adapter.
• Modernizing the pinned Ionide helper toolchain during the first proof.
• Completion, references, rename, code actions, or broader IDE parity beyond the existing Semantic Feature Slice.
• Implicit restore, build, publish, test, or project execution during extension activation.
• Arbitrary shell commands or unrestricted server argument configuration.
• Launching an interactive VS Code GUI from normal CI builds.
• A headless VS Code test runner as a replacement for the editor-driven proof; it may be added later as a separate target.
• Implementing a second editor adapter as part of this issue.

Further Notes

The proof is intentionally a thin Editor Adapter around the existing Four-Role Executable. The acceptance goal is not extension polish; it is observable evidence that the new LSP works in a real editor and that future editor adapters can reuse the same public protocol, Workspace Control Plane, and shared fixture.

Start by locating the existing FAKE build pipeline, End-to-End LSP Harness, LSP runtime tests, and shared mixed-language fixture; the issue names no specific files. Define the VS Code-namespaced restore, build, package, and proof targets there, then verify native and managed Coordinator launches and the editor-driven acceptance flow. Done means CI-safe artifacts plus a local disposable-profile proof covering diagnostics, hover, navigation, status, and reload.