feat(DevTools): Modernize gRPC ui with Svelte 5 and Vite

.coderabbit.yaml

@@ -5,7 +5,7 @@ language: en-US
 early_access: false
 
 reviews:
-  profile: assertive
+  profile: thorough
   request_changes_workflow: false
   high_level_summary: true
   poem: false

Dockerfile

@@ -38,7 +38,8 @@ FROM node:22 AS ui
 WORKDIR /ui
 COPY ["src/Plugins/Solutions/DevTools/UI/package.json", "src/Plugins/Solutions/DevTools/UI/package-lock.json", "./"]
 RUN npm ci
-COPY ["src/Plugins/Solutions/DevTools/UI/template.html", "src/Plugins/Solutions/DevTools/UI/build.mjs", "./"]
+COPY ["src/Plugins/Solutions/DevTools/UI/template.html", "src/Plugins/Solutions/DevTools/UI/vite.config.ts", "src/Plugins/Solutions/DevTools/UI/svelte.config.js", "./"]
+COPY ["src/Plugins/Solutions/DevTools/UI/scripts/", "./scripts/"]
 COPY ["src/Plugins/Solutions/DevTools/UI/src/", "./src/"]
 RUN npm run build
 

Docs/ADR/020-devtools-plugin.md

@@ -43,6 +43,75 @@ Both developer tools move into single `DevTools` plugin (`src/Plugins/Solutions/
 - A gRPC proxy process (eg. maintained third party gRPC UI binary) for streaming and health support additional deployment process and transport hop the extra support was deemed unnecessary for an internal developer tool.
 - Serving Swagger from the plugin while re-emitting document generation there would duplicate `AddSwaggerGen` configuration generation stays in the host, serving stays in the plugin.
 
+## HTTP API Contract
+
+The DevTools plugin exposes two JSON API endpoints consumed by the TypeScript frontend:
+
+### `/api/services` — GrpcCatalogResponse
+
+Returns the discovered gRPC services for the catalog:
+
+```csharp
+public sealed class GrpcCatalogResponse
+{
+    public required string Target { get; init; }
+    public required IEnumerable<GrpcServiceInfo> Services { get; init; }
+}
+
+public sealed class GrpcServiceInfo
+{
+    public required string Name { get; init; }      // Short service name
+    public required string FullName { get; init; }  // Fully qualified name
+    public string? Description { get; init; }       // Nullable proto doc comment (null = absent)
+    public required string Package { get; init; }
+    public required string FileName { get; init; }
+    public bool IsPlugin { get; init; }              // Default: false (backward-compatible for host services)
+    public required IEnumerable<GrpcMethodInfo> Methods { get; init; }
+}
+```
+
+- `Description`: Nullable string from proto documentation. Absent (`null`) when proto has no comment.
+- `IsPlugin`: Defaults to `false` for host services, enabling backward compatibility with non-plugin assemblies.
+
+### `/api/invoke` — GrpcInvocationRequest → GrpcInvocationResult
+
+Executes a unary gRPC method:
+
+```csharp
+public sealed class GrpcInvocationRequest
+{
+    public required string Service { get; init; }
+    public required string Method { get; init; }
+    public required string RequestJson { get; init; }
+    public IReadOnlyDictionary<string, string> Headers { get; init; } = new Dictionary<string, string>();
+}
+
+public sealed class GrpcInvocationResult
+{
+    public required bool Success { get; init; }
+    public required string StatusName { get; init; }
+    public required int StatusCode { get; init; }
+    public string? Detail { get; init; }
+    public string? ResponseJson { get; init; }
+    public string? ResponseBase64 { get; init; }    // Success-only base64-encoded protobuf payload; null on failure
+    public double ElapsedMs { get; init; }
+    public IReadOnlyDictionary<string, string>? Trailers { get; init; }
+}
+```
+
+- `ResponseBase64`: Only populated on successful invocations (`Success == true`). Contains raw protobuf bytes encoded as base64.
+- **Payload size limit**: The base64 payload is limited to `int.MaxValue - 1` bytes (≈2 GB) due to protobuf size constraints.
+- `ResponseJson`: Present only on success, containing JSON-formatted response via protobuf JSON formatter.
+- Failed invocations return `Success = false` with `Detail` and `Trailers` populated for debugging.
+
+### JSON Serialization
+
+All DTOs are serialized using `System.Text.Json` with `JsonSerializerDefaults.Web` for consistent casing:
+
+- PascalCase property names in JSON (e.g., `"ResponseBase64"`, `"IsPlugin"`).
+- Nullable fields are omitted when null (default ASP.NET Core JSON behavior).
+- Boolean fields with `false` values are included (not omitted).
+
 ## Consequences
 
 The host's `AppMiddlewareConfiguration` is smaller and no longer references Swashbuckle. The `DevTools` solution owns compiler friendly tooling code (catalog, invoker, middleware, options, and UI assets). Swagger UI availability depends on plugin deployment and environment gating rather than host build configuration. The gRPC UI only supports unary methods streaming methods are reported as unsupported rather than approximated. Configuration is centralized in `DevToolsOptions`, resolved with environment variables (`GRPC_UI_TARGET`, `DEV_CERT_PORT_GRPC`) for local development against the HTTPS gRPC endpoint.

Docs/ADR/026-plugin-authentication-and-authorization-hooks.md

@@ -1,4 +1,4 @@
-[ADR Home](../../README.md) | [Category Index](./README.md) | [Previous](./025-plugin-options-openapi-and-marten-integrations.md) | [Next]()
+[ADR Home](../../README.md) | [Category Index](./README.md) | [Previous](./025-plugin-options-openapi-and-marten-integrations.md) | [Next](./027-devtools-ui-typescript.md)
 
 # [ADR-026] Configure Plugin Authentication And Authorization Through Host Security Infrastructure
 
@@ -46,4 +46,4 @@ Plugin schemes and policies can protect plugin endpoints through normal ASP.NET
 - [ADR-023](./023-plugin-application-pipeline-hooks.md) - plugin endpoints and middleware pipeline
 - [Issue #12](https://github.com/AuthKits/AuthKit.Server/issues/12) - authentication and authorization hooks
 
-[ADR Home](../../README.md) | [Category Index](./README.md) | [Previous](./025-plugin-options-openapi-and-marten-integrations.md) | [Next]()
+[ADR Home](../../README.md) | [Category Index](./README.md) | [Previous](./025-plugin-options-openapi-and-marten-integrations.md) | [Next](./027-devtools-ui-typescript.md)

Docs/ADR/README.md

@@ -77,6 +77,7 @@ The table below shows the architecture areas and their current scope.
 | [ADR-024](./024-plugin-lifecycle-and-hosted-services.md) | Bridge Plugin Lifecycle Hooks To The Standard .NET Host Lifecycle | Plugins | accepted | 2026-09-12 |
 | [ADR-025](./025-plugin-options-openapi-and-marten-integrations.md) | Keep Plugin Options, OpenAPI, And Marten Integrations Explicit | Plugins | accepted | 2026-09-12 |
 | [ADR-026](./026-plugin-authentication-and-authorization-hooks.md) | Configure Plugin Authentication And Authorization Through Host Security Infrastructure | Plugins | accepted | 2026-09-12 |
+| [ADR-027](./027-devtools-ui-typescript.md) | Compile The DevTools UI From Modular TypeScript Into A Single Embedded Resource | Plugins | accepted | 2026-09-16 |
 
 ## Relationships Between Areas
 

docker-compose.yml

@@ -9,14 +9,15 @@ services:
       - "5000:5000"  # REST HTTPS
       - "5001:5001"  # gRPC HTTPS
     depends_on:
-      - authdev-db
+      authdev-db:
+        condition: service_healthy
     volumes:
       - ./certs:/root/certs
     env_file:
       - .env
     environment:
       - ASPNETCORE_ENVIRONMENT=Development
-      - ConnectionStrings__DefaultConnection=Host=auth-db;Port=5432;Database=AuthDev;Username=postgres;Password=postgres
+      - ConnectionStrings__DefaultConnection=Host=authdev-db;Port=5432;Database=AuthDev;Username=postgres;Password=postgres
     healthcheck:
       test: ["CMD", "curl", "-k", "-f", "https://localhost:5000/health"]
       interval: 30s
@@ -36,6 +37,11 @@ services:
       - "5434:5432"
     volumes:
       - AuthDev-data:/var/lib/postgresql/data
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U postgres -d AuthDev"]
+      interval: 5s
+      timeout: 5s
+      retries: 10
     networks:
       - db_net
 

src/Host/Host.csproj

@@ -30,6 +30,11 @@
   <ItemGroup>
     <Protobuf Include="Grpc\protos\**\*.proto" ProtoRoot="Grpc" GrpcServices="Both" Access="Public" />
   </ItemGroup>
+  <ItemGroup>
+    <Content Include="Grpc\protos\**\*.proto">
+      <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
+    </Content>
+  </ItemGroup>
   <ItemGroup>
     <ProjectReference Include="..\Core\Core.csproj" />
     <ProjectReference Include="..\Plugins\Abstractions\AuthKit.Plugins.Abstractions.csproj" />

src/Plugins/Solutions/DevTools/Catalog/GrpcServiceCatalog.cs

@@ -1,7 +1,9 @@
 using System.Reflection;
 using System.Runtime.Loader;
+using AuthKit.Plugins.Abstractions.Contracts.Plugins;
 using Google.Protobuf.Reflection;
 using Microsoft.Extensions.Logging;
+using IAuthKitPlugin = AuthKit.Plugins.Abstractions.Contracts.PluginContract.IAuthKitPlugin;
 
 namespace DevTools.Catalog;
 
@@ -81,10 +83,11 @@
 
                     try
                     {
-                        services.Add(BuildServiceInfo(descriptor));
+                        var comments = CommentsFor(descriptor.File, assembly, logger);
+                        services.Add(BuildServiceInfo(descriptor, comments, assembly));
                         foreach (var method in descriptor.Methods)
                             methods[$"{descriptor.FullName}/{method.Name}"] =
-                                new GrpcMethodCatalogEntry(BuildMethodInfo(method), method);
+                                new GrpcMethodCatalogEntry(BuildMethodInfo(method, comments), method);
                     }
                     catch (Exception ex)
                     {
@@ -112,46 +115,91 @@
         }
     }
 
-    private static GrpcServiceInfo BuildServiceInfo(ServiceDescriptor descriptor) =>
+    private static GrpcServiceInfo BuildServiceInfo(ServiceDescriptor descriptor,
+        IReadOnlyDictionary<string, string> comments, Assembly assembly) =>
         new()
         {
             Name = descriptor.Name,
             FullName = descriptor.FullName,
+            Description = comments.TryGetValue(descriptor.Name, out var summary) ? summary : null,
             Package = descriptor.File.Package,
             FileName = descriptor.File.Name,
+            IsPlugin = IsPluginAssembly(assembly),
             Methods = descriptor.Methods
-                .Select(BuildMethodInfo)
+                .Select(method => BuildMethodInfo(method, comments))
                 .ToArray()
         };
 
-    private static GrpcMethodInfo BuildMethodInfo(MethodDescriptor method) =>
+    private static bool IsPluginAssembly(Assembly assembly)
+    {
+        var assemblyName = assembly.GetName().Name ?? string.Empty;
+        if (string.Equals(assemblyName, "Host", StringComparison.OrdinalIgnoreCase) ||
+            assembly == Assembly.GetEntryAssembly())
+        {
+            return false;
+        }
+
+        if (assembly.GetCustomAttribute<PluginMetadataAttribute>() is not null)
+        {
+            return true;
+        }
+
+        var types = SafeGetTypes(assembly);
+        if (types.Any(t => typeof(IAuthKitPlugin).IsAssignableFrom(t) && !t.IsInterface && !t.IsAbstract))
+        {
+            return true;
+        }
+
+        if (assemblyName.StartsWith("System.", StringComparison.OrdinalIgnoreCase) ||
+            assemblyName.StartsWith("Microsoft.", StringComparison.OrdinalIgnoreCase) ||
+            assemblyName.StartsWith("Google.", StringComparison.OrdinalIgnoreCase) ||
+            string.Equals(assemblyName, "Core", StringComparison.OrdinalIgnoreCase))
+        {
+            return false;
+        }
+
+        return false;
+    }
+
+    private static GrpcMethodInfo BuildMethodInfo(MethodDescriptor method,
+        IReadOnlyDictionary<string, string> comments) =>
         new()
         {
             Name = method.Name,
             FullName = $"{method.Service.FullName}/{method.Name}",
+            Description = comments.TryGetValue($"{method.Service.Name}.{method.Name}", out var summary)
+                ? summary
+                : null,
             IsClientStreaming = method.IsClientStreaming,
             IsServerStreaming = method.IsServerStreaming,
-            Request = BuildMessageSchema(method.InputType, depth: 0),
-            Response = BuildMessageSchema(method.OutputType, depth: 0)
+            Request = BuildMessageSchema(method.InputType, depth: 0, comments),
+            Response = BuildMessageSchema(method.OutputType, depth: 0, comments)
         };
 
-    private static GrpcMessageSchema BuildMessageSchema(MessageDescriptor message, int depth) =>
+    private static GrpcMessageSchema BuildMessageSchema(MessageDescriptor message, int depth,
+        IReadOnlyDictionary<string, string> comments) =>
         new()
         {
             Name = message.Name,
             FullName = message.FullName,
+            Description = comments.TryGetValue(message.Name, out var summary) ? summary : null,
             Fields = depth >= MaxMessageDepth
                 ? []
                 : message.Fields.InFieldNumberOrder()
-                    .Select(field => BuildFieldSchema(field, depth))
+                    .Select(field => BuildFieldSchema(field, depth, comments))
                     .ToArray()
         };
 
-    private static GrpcFieldSchema BuildFieldSchema(FieldDescriptor field, int depth)
+    private static GrpcFieldSchema BuildFieldSchema(FieldDescriptor field, int depth,
+        IReadOnlyDictionary<string, string> comments)
     {
         var schema = new GrpcFieldSchema
         {
+            Number = field.FieldNumber,
             Name = field.Name,
+            Description = comments.TryGetValue($"{field.ContainingType.Name}.{field.Name}", out var summary)
+                ? summary
+                : null,
             FieldType = field.FieldType.ToString(),
             IsRepeated = field.IsRepeated,
             IsMap = field.IsMap
@@ -164,13 +212,13 @@
 
             schema.MapKeyType = keyField.FieldType.ToString();
             if (valueField.FieldType == FieldType.Message)
-                schema.MapValue = BuildMessageSchema(valueField.MessageType, depth + 1);
+                schema.MapValue = BuildMessageSchema(valueField.MessageType, depth + 1, comments);
             else
                 schema.MapValueType = valueField.FieldType.ToString();
         }
 
         if (field is { FieldType: FieldType.Message, IsMap: false })
-            schema.Message = BuildMessageSchema(field.MessageType, depth + 1);
+            schema.Message = BuildMessageSchema(field.MessageType, depth + 1, comments);
 
         if (field.FieldType == FieldType.Enum)
         {
@@ -180,4 +228,26 @@
 
         return schema;
     }
-}
+
+    private static IReadOnlyDictionary<string, string> CommentsFor(FileDescriptor file,
+        Assembly assembly, ILogger<GrpcServiceCatalog> logger)
+    {
+        var roots = assembly.Location is { Length: > 0 } location
+            ? new[] { Path.GetDirectoryName(location) }
+            : null;
+
+        var path = ProtoDocComments.TryResolvePath(file.Name, roots);
+        if (path is null)
+            return new Dictionary<string, string>(StringComparer.Ordinal);
+
+        try
+        {
+            return ProtoDocComments.Parse(path);
+        }
+        catch (Exception ex)
+        {
+            logger.LogDebug(ex, "Failed to parse proto comments from {Path}.", path);
+            return new Dictionary<string, string>(StringComparer.Ordinal);
+        }
+    }
+}