Add plugin isolation IPC scaffolding and host phase one docs

LanMountainDesktop.PluginIsolation.Contracts/AppearanceContracts.cs

@@ -0,0 +1,12 @@
+namespace LanMountainDesktop.PluginIsolation.Contracts;
+
+public sealed record PluginAppearanceSnapshotRequest(string SessionId);
+
+public sealed record PluginAppearanceSnapshot(
+    string ThemeVariant,
+    string? AccentColor = null,
+    double CornerRadiusScale = 1.0,
+    IReadOnlyDictionary<string, double>? CornerRadiusTokens = null,
+    IReadOnlyDictionary<string, string>? ResourceAliases = null);
+
+public sealed record PluginAppearanceChangedNotification(PluginAppearanceSnapshot Snapshot);

LanMountainDesktop.PluginIsolation.Contracts/DiagnosticsContracts.cs

@@ -0,0 +1,45 @@
+namespace LanMountainDesktop.PluginIsolation.Contracts;
+
+public sealed record PluginHeartbeatPing(
+    string SessionId,
+    DateTimeOffset SentAtUtc);
+
+public sealed record PluginHeartbeatPong(
+    string SessionId,
+    DateTimeOffset ReceivedAtUtc);
+
+public sealed record PluginLogEntry(
+    string Level,
+    string Category,
+    string Message,
+    DateTimeOffset TimestampUtc,
+    string? Exception = null);
+
+public static class PluginLogLevels
+{
+    public const string Trace = "trace";
+    public const string Debug = "debug";
+    public const string Information = "information";
+    public const string Warning = "warning";
+    public const string Error = "error";
+    public const string Critical = "critical";
+}
+
+public sealed record PluginFaultReport(
+    string SessionId,
+    string FaultKind,
+    bool IsFatal,
+    string Message,
+    string? StackTrace = null,
+    int? WorkerProcessId = null,
+    int? ExitCode = null,
+    DateTimeOffset? OccurredAtUtc = null);
+
+public static class PluginFaultKinds
+{
+    public const string ManagedException = "managed-exception";
+    public const string NativeCrash = "native-crash";
+    public const string WatchdogTimeout = "watchdog-timeout";
+    public const string StartupFailure = "startup-failure";
+    public const string ForcedTermination = "forced-termination";
+}

LanMountainDesktop.PluginIsolation.Contracts/LanMountainDesktop.PluginIsolation.Contracts.csproj

@@ -0,0 +1,22 @@
+<Project Sdk="Microsoft.NET.Sdk">
+  <PropertyGroup>
+    <TargetFramework>net10.0</TargetFramework>
+    <Nullable>enable</Nullable>
+    <ImplicitUsings>enable</ImplicitUsings>
+    <Version>1.0.0</Version>
+    <PackageId>LanMountainDesktop.PluginIsolation.Contracts</PackageId>
+    <IsPackable>true</IsPackable>
+    <Authors>LanMountainDesktop</Authors>
+    <Description>Transport-neutral IPC contracts for the LanMountainDesktop plugin isolation architecture.</Description>
+    <PackageTags>LanMountainDesktop;Plugin;IPC;Isolation;Contracts</PackageTags>
+    <PackageReadmeFile>README.md</PackageReadmeFile>
+    <RepositoryUrl>https://github.com/wwiinnddyy/LanMountainDesktop</RepositoryUrl>
+    <RepositoryType>git</RepositoryType>
+    <PackageLicenseExpression>LGPL-3.0-or-later</PackageLicenseExpression>
+    <Copyright>Copyright (c) LanMountainDesktop Contributors</Copyright>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <None Include="README.md" Pack="true" PackagePath="\" />
+  </ItemGroup>
+</Project>

LanMountainDesktop.PluginIsolation.Contracts/LifecycleContracts.cs

@@ -0,0 +1,33 @@
+namespace LanMountainDesktop.PluginIsolation.Contracts;
+
+public sealed record PluginInitializeRequest(
+    string PluginId,
+    string SessionId,
+    string HostPipeName,
+    string DataDirectory,
+    IReadOnlyDictionary<string, string>? StartupProperties = null);
+
+public sealed record PluginInitializeResponse(
+    bool Succeeded,
+    string? ErrorCode = null,
+    string? ErrorMessage = null);
+
+public sealed record PluginStopRequest(
+    string Reason,
+    bool RestartRequested = false);
+
+public sealed record PluginRestartRequest(string Reason);
+
+public sealed record PluginLifecycleStateChanged(
+    string State,
+    string? Detail = null);
+
+public static class PluginLifecycleStates
+{
+    public const string Starting = "starting";
+    public const string Ready = "ready";
+    public const string Degraded = "degraded";
+    public const string Stopping = "stopping";
+    public const string Stopped = "stopped";
+    public const string Faulted = "faulted";
+}

LanMountainDesktop.PluginIsolation.Contracts/PluginCapabilityDeclaration.cs

@@ -0,0 +1,17 @@
+namespace LanMountainDesktop.PluginIsolation.Contracts;
+
+public sealed record PluginCapabilityDeclaration(
+    string Name,
+    string Version,
+    string? Description = null);
+
+public static class PluginCapabilityNames
+{
+    public const string Settings = "settings";
+    public const string Appearance = "appearance";
+    public const string DesktopComponentUi = "ui.desktop-component";
+    public const string ComponentEditorUi = "ui.component-editor";
+    public const string SettingsPageUi = "ui.settings-page";
+    public const string Logging = "diagnostics.log";
+    public const string FaultReporting = "diagnostics.fault";
+}

LanMountainDesktop.PluginIsolation.Contracts/PluginIpcErrorCodes.cs

@@ -0,0 +1,15 @@
+namespace LanMountainDesktop.PluginIsolation.Contracts;
+
+public static class PluginIpcErrorCodes
+{
+    public const string ProtocolMismatch = "protocol_mismatch";
+    public const string SessionRejected = "session_rejected";
+    public const string CapabilityDenied = "capability_denied";
+    public const string InvalidRequest = "invalid_request";
+    public const string UnsupportedRoute = "unsupported_route";
+    public const string SettingsConflict = "settings_conflict";
+    public const string UiAttachRejected = "ui_attach_rejected";
+    public const string WorkerFaulted = "worker_faulted";
+    public const string WorkerExited = "worker_exited";
+    public const string HeartbeatTimeout = "heartbeat_timeout";
+}

LanMountainDesktop.PluginIsolation.Contracts/PluginIpcRoutes.cs

@@ -0,0 +1,56 @@
+namespace LanMountainDesktop.PluginIsolation.Contracts;
+
+public static class PluginIpcRoutes
+{
+    public static class Session
+    {
+        public const string Handshake = "session/handshake";
+        public const string Capabilities = "session/capabilities";
+        public const string Ready = "session/ready";
+    }
+
+    public static class Lifecycle
+    {
+        public const string Initialize = "lifecycle/initialize";
+        public const string Stop = "lifecycle/stop";
+        public const string RestartRequest = "lifecycle/restart-request";
+        public const string StateChanged = "lifecycle/state-changed";
+    }
+
+    public static class Settings
+    {
+        public const string GetSnapshot = "settings/get-snapshot";
+        public const string Write = "settings/write";
+        public const string Changed = "settings/changed";
+    }
+
+    public static class Appearance
+    {
+        public const string GetSnapshot = "appearance/get-snapshot";
+        public const string Changed = "appearance/changed";
+    }
+
+    public static class Ui
+    {
+        public const string Attach = "ui/attach";
+        public const string Detach = "ui/detach";
+        public const string Command = "ui/command";
+        public const string StateChanged = "ui/state-changed";
+    }
+
+    public static class Heartbeat
+    {
+        public const string Ping = "heartbeat/ping";
+        public const string Pong = "heartbeat/pong";
+    }
+
+    public static class Log
+    {
+        public const string Write = "log/write";
+    }
+
+    public static class Fault
+    {
+        public const string Report = "fault/report";
+    }
+}

LanMountainDesktop.PluginIsolation.Contracts/PluginIsolationJsonContext.cs

@@ -0,0 +1,39 @@
+using System.Text.Json.Serialization;
+
+namespace LanMountainDesktop.PluginIsolation.Contracts;
+
+[JsonSourceGenerationOptions(
+    PropertyNamingPolicy = JsonKnownNamingPolicy.CamelCase,
+    PropertyNameCaseInsensitive = true,
+    DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingNull)]
+[JsonSerializable(typeof(PluginCapabilityDeclaration))]
+[JsonSerializable(typeof(List<PluginCapabilityDeclaration>))]
+[JsonSerializable(typeof(PluginSessionHandshakeRequest))]
+[JsonSerializable(typeof(PluginSessionHandshakeResponse))]
+[JsonSerializable(typeof(PluginReadyNotification))]
+[JsonSerializable(typeof(PluginInitializeRequest))]
+[JsonSerializable(typeof(PluginInitializeResponse))]
+[JsonSerializable(typeof(PluginStopRequest))]
+[JsonSerializable(typeof(PluginRestartRequest))]
+[JsonSerializable(typeof(PluginLifecycleStateChanged))]
+[JsonSerializable(typeof(PluginSettingsSnapshotRequest))]
+[JsonSerializable(typeof(PluginSettingsSnapshotResponse))]
+[JsonSerializable(typeof(PluginSettingsWriteRequest))]
+[JsonSerializable(typeof(PluginSettingsWriteResponse))]
+[JsonSerializable(typeof(PluginSettingsChangedNotification))]
+[JsonSerializable(typeof(PluginAppearanceSnapshotRequest))]
+[JsonSerializable(typeof(PluginAppearanceSnapshot))]
+[JsonSerializable(typeof(PluginAppearanceChangedNotification))]
+[JsonSerializable(typeof(PluginUiSurfaceDescriptor))]
+[JsonSerializable(typeof(List<PluginUiSurfaceDescriptor>))]
+[JsonSerializable(typeof(PluginUiAttachRequest))]
+[JsonSerializable(typeof(PluginUiAttachResponse))]
+[JsonSerializable(typeof(PluginUiDetachNotification))]
+[JsonSerializable(typeof(PluginUiCommandRequest))]
+[JsonSerializable(typeof(PluginUiCommandResponse))]
+[JsonSerializable(typeof(PluginUiStateChangedNotification))]
+[JsonSerializable(typeof(PluginHeartbeatPing))]
+[JsonSerializable(typeof(PluginHeartbeatPong))]
+[JsonSerializable(typeof(PluginLogEntry))]
+[JsonSerializable(typeof(PluginFaultReport))]
+public partial class PluginIsolationJsonContext : JsonSerializerContext;

LanMountainDesktop.PluginIsolation.Contracts/PluginIsolationProtocolVersion.cs

@@ -0,0 +1,6 @@
+namespace LanMountainDesktop.PluginIsolation.Contracts;
+
+public static class PluginIsolationProtocolVersion
+{
+    public const string Current = "1.0";
+}

LanMountainDesktop.PluginIsolation.Contracts/README.md

@@ -0,0 +1,9 @@
+# LanMountainDesktop.PluginIsolation.Contracts
+
+Transport-neutral DTOs, route constants, protocol versioning, and JSON serialization context for plugin process isolation.
+
+## Includes
+
+- route groups for session, lifecycle, settings, appearance, UI, heartbeat, log, and fault
+- explicit DTOs for routed request and notification payloads
+- source-generated `System.Text.Json` context for the IPC protocol

LanMountainDesktop.PluginIsolation.Contracts/SessionContracts.cs

@@ -0,0 +1,21 @@
+namespace LanMountainDesktop.PluginIsolation.Contracts;
+
+public sealed record PluginSessionHandshakeRequest(
+    string PluginId,
+    string SessionId,
+    string RuntimeMode,
+    string ProtocolVersion,
+    IReadOnlyList<PluginCapabilityDeclaration>? RequestedCapabilities = null,
+    IReadOnlyDictionary<string, string>? Metadata = null);
+
+public sealed record PluginSessionHandshakeResponse(
+    bool Accepted,
+    string ProtocolVersion,
+    IReadOnlyList<PluginCapabilityDeclaration>? GrantedCapabilities = null,
+    string? ErrorCode = null,
+    string? ErrorMessage = null);
+
+public sealed record PluginReadyNotification(
+    string PluginId,
+    string SessionId,
+    IReadOnlyList<PluginUiSurfaceDescriptor>? UiSurfaces = null);

LanMountainDesktop.PluginIsolation.Contracts/SettingsContracts.cs

@@ -0,0 +1,33 @@
+using System.Text.Json;
+
+namespace LanMountainDesktop.PluginIsolation.Contracts;
+
+public sealed record PluginSettingsSnapshotRequest(
+    string Scope,
+    string? SectionId = null,
+    string? ComponentInstanceId = null);
+
+public sealed record PluginSettingsSnapshotResponse(
+    string Scope,
+    JsonElement Snapshot,
+    string? ETag = null);
+
+public sealed record PluginSettingsWriteRequest(
+    string Scope,
+    JsonElement Value,
+    string? SectionId = null,
+    string? ComponentInstanceId = null,
+    string? ETag = null);
+
+public sealed record PluginSettingsWriteResponse(
+    bool Accepted,
+    string? ETag = null,
+    string? ErrorCode = null,
+    string? ErrorMessage = null);
+
+public sealed record PluginSettingsChangedNotification(
+    string Scope,
+    JsonElement Value,
+    string? SectionId = null,
+    string? ComponentInstanceId = null,
+    string? ETag = null);

LanMountainDesktop.PluginIsolation.Contracts/UiContracts.cs

@@ -0,0 +1,52 @@
+using System.Text.Json;
+
+namespace LanMountainDesktop.PluginIsolation.Contracts;
+
+public sealed record PluginUiSurfaceDescriptor(
+    string SurfaceId,
+    string SurfaceKind,
+    string Title,
+    string? ComponentId = null);
+
+public static class PluginUiSurfaceKinds
+{
+    public const string DesktopComponent = "desktop-component";
+    public const string ComponentEditor = "component-editor";
+    public const string SettingsPage = "settings-page";
+    public const string Window = "window";
+}
+
+public sealed record PluginUiAttachRequest(
+    string SurfaceId,
+    string SurfaceKind,
+    string? InstanceId = null,
+    JsonElement? InitialState = null);
+
+public sealed record PluginUiAttachResponse(
+    bool Accepted,
+    JsonElement? InitialState = null,
+    string? ErrorCode = null,
+    string? ErrorMessage = null);
+
+public sealed record PluginUiDetachNotification(
+    string SurfaceId,
+    string SurfaceKind,
+    string? InstanceId = null);
+
+public sealed record PluginUiCommandRequest(
+    string SurfaceId,
+    string CommandName,
+    string? InstanceId = null,
+    JsonElement? Payload = null);
+
+public sealed record PluginUiCommandResponse(
+    bool Accepted,
+    JsonElement? Payload = null,
+    string? ErrorCode = null,
+    string? ErrorMessage = null);
+
+public sealed record PluginUiStateChangedNotification(
+    string SurfaceId,
+    string SurfaceKind,
+    string? InstanceId = null,
+    JsonElement? State = null);