Add identity web composition and docs workflow

Author: Hongwei-MB

.nuke/build.schema.json

@@ -28,6 +28,8 @@
         "Build",
         "Clean",
         "CoverageReport",
+        "Doc",
+        "DocsBuild",
         "Format",
         "GenerateReleaseManifest",
         "Init",
@@ -142,6 +144,11 @@
           "description": "Minimum line coverage percentage (0-100). CoverageReport fails if below this threshold",
           "format": "int32"
         },
+        "DocsPort": {
+          "type": "integer",
+          "description": "Port used by Doc target",
+          "format": "int32"
+        },
         "NuGetApiKey": {
           "type": "string",
           "description": "NuGet API key for PushNuGetPackages target. Defaults to NUGET_API_KEY environment variable"
@@ -150,6 +157,10 @@
           "type": "string",
           "description": "New project name for Init target (e.g. Acme.Payments)"
         },
+        "PublishHost": {
+          "type": "string",
+          "description": "Host to publish - supported values are 'web' and 'cli'"
+        },
         "ResetGit": {
           "type": "boolean",
           "description": "Reset git history to a fresh commit during Init"

ChengYuan.slnx

@@ -39,6 +39,7 @@
     <Project Path="src/Applications/ChengYuan.Identity/ChengYuan.Identity.Domain/ChengYuan.Identity.Domain.csproj" />
     <Project Path="src/Applications/ChengYuan.Identity/ChengYuan.Identity.Application/ChengYuan.Identity.Application.csproj" />
     <Project Path="src/Applications/ChengYuan.Identity/ChengYuan.Identity.Persistence/ChengYuan.Identity.Persistence.csproj" />
+    <Project Path="src/Applications/ChengYuan.Identity/ChengYuan.Identity.Web/ChengYuan.Identity.Web.csproj" />
     <Project Path="src/Applications/ChengYuan.PermissionManagement/ChengYuan.PermissionManagement.Contracts/ChengYuan.PermissionManagement.Contracts.csproj" />
     <Project Path="src/Applications/ChengYuan.PermissionManagement/ChengYuan.PermissionManagement.Application/ChengYuan.PermissionManagement.Application.csproj" />
     <Project Path="src/Applications/ChengYuan.PermissionManagement/ChengYuan.PermissionManagement.Persistence/ChengYuan.PermissionManagement.Persistence.csproj" />

Directory.Packages.props

@@ -10,6 +10,7 @@
     <PackageVersion Include="Microsoft.Extensions.Caching.Memory" Version="10.0.0" />
     <PackageVersion Include="Microsoft.Extensions.DependencyInjection" Version="10.0.0" />
     <PackageVersion Include="Microsoft.Extensions.DependencyInjection.Abstractions" Version="10.0.0" />
+    <PackageVersion Include="Microsoft.AspNetCore.TestHost" Version="10.0.0" />
     <PackageVersion Include="Microsoft.EntityFrameworkCore" Version="10.0.0" />
     <PackageVersion Include="Microsoft.EntityFrameworkCore.InMemory" Version="10.0.0" />
     <!-- Analyzers -->

build/BuildTask.Helpers.cs

@@ -1,3 +1,7 @@
+using System;
+using System.Diagnostics;
+using System.IO;
+using Nuke.Common;
 using Nuke.Common.Tools.DotNet;
 
 partial class BuildTask
@@ -13,4 +17,58 @@ DotNetPublishSettings ApplyVersionSuffix(DotNetPublishSettings settings) =>
 
     DotNetTestSettings ApplyVersionSuffix(DotNetTestSettings settings) =>
         string.IsNullOrWhiteSpace(VersionSuffix) ? settings : settings.SetProperty("VersionSuffix", VersionSuffix);
+
+    void EnsureDocsDependencies()
+    {
+        if (Directory.Exists(DocsNodeModulesDirectory))
+        {
+            Serilog.Log.Information("Skipping docs dependency install because node_modules already exists.");
+            return;
+        }
+
+        var installCommand = File.Exists(DocsPackageLockFile) ? "ci" : "install";
+        Serilog.Log.Information("Installing docs dependencies with 'npm {InstallCommand}'.", installCommand);
+        RunNpmCommandAndAssert(installCommand, DocsDirectory);
+    }
+
+    void BuildDocsSite()
+    {
+        Serilog.Log.Information("Building docs site.");
+        RunNpmCommandAndAssert("run docs:build", DocsDirectory);
+    }
+
+    void RunNpmCommandAndAssert(string arguments, string workingDirectory)
+    {
+        var (fileName, resolvedArguments) = CreateNpmInvocation(arguments);
+        RunCommandAndAssert(fileName, resolvedArguments, workingDirectory);
+    }
+
+    (string FileName, string Arguments) CreateNpmInvocation(string arguments)
+    {
+        return OperatingSystem.IsWindows()
+            ? ("cmd.exe", $"/c npm.cmd {arguments}")
+            : ("npm", arguments);
+    }
+
+    void RunCommandAndAssert(string fileName, string arguments, string workingDirectory)
+    {
+        using var process = Process.Start(new ProcessStartInfo
+        {
+            FileName = fileName,
+            Arguments = arguments,
+            WorkingDirectory = workingDirectory,
+            UseShellExecute = false,
+            RedirectStandardOutput = false,
+            RedirectStandardError = false,
+            CreateNoWindow = true
+        }) ?? throw new InvalidOperationException($"Failed to start process '{fileName}'.");
+
+        process.WaitForExit();
+
+        if (process.ExitCode != 0)
+        {
+            throw new InvalidOperationException($"Process '{fileName} {arguments}' exited with code {process.ExitCode}.");
+        }
+    }
+
 }

build/BuildTask.Parameters.cs

@@ -13,13 +13,13 @@ partial class BuildTask
     readonly string VersionSuffix = string.Empty;
 
     [Parameter("Host to publish - supported values are 'web' and 'cli'")]
-    new readonly string Host = string.Empty;
+    readonly string PublishHost = string.Empty;
 
     // Internal path conventions controlled by build tasks (not external parameters).
     readonly string BuildPath = "ChengYuan.slnx";
     readonly string TestPath = "ChengYuan.slnx";
     readonly string PackPath = "ChengYuan.slnx";
-    string NormalizedHost => Host.Trim().ToLowerInvariant();
+    string NormalizedHost => PublishHost.Trim().ToLowerInvariant();
     string PublishPath => NormalizedHost switch
     {
         "web" => "src/Hosts/ChengYuan.WebHost/ChengYuan.WebHost.csproj",
@@ -34,6 +34,9 @@ partial class BuildTask
     [Parameter("Publish self-contained output in Publish target")]
     readonly bool SelfContained;
 
+    [Parameter("Port used by Doc target")]
+    readonly int DocsPort = 5173;
+
     [Parameter("NuGet API key for PushNuGetPackages target. Defaults to NUGET_API_KEY environment variable.")]
     readonly string NuGetApiKey = string.Empty;
 
@@ -58,6 +61,9 @@ partial class BuildTask
     AbsolutePath PackagesDirectory => ArtifactsDirectory / "packages";
     AbsolutePath PublishDirectory => ArtifactsDirectory / "publish";
     AbsolutePath InstallersDirectory => ArtifactsDirectory / "installers";
+    AbsolutePath DocsDirectory => RootDirectory / "docs";
+    AbsolutePath DocsNodeModulesDirectory => DocsDirectory / "node_modules";
+    AbsolutePath DocsPackageLockFile => DocsDirectory / "package-lock.json";
 
     AbsolutePath ReleaseManifestFile => PackagesDirectory / "release-manifest.json";
     AbsolutePath BuildOutputsMarkerFile => ArtifactsDirectory / ".build-outputs" / "build-outputs.json";

build/BuildTask.Targets.Docs.cs

@@ -0,0 +1,19 @@
+using Nuke.Common;
+
+partial class BuildTask
+{
+    Target Doc => _ => _
+        .DependsOn(DocsBuild)
+        .Executes(() =>
+        {
+            Serilog.Log.Information("Starting docs development server on http://localhost:{DocsPort}.", DocsPort);
+            RunNpmCommandAndAssert($"run docs:dev:restart -- --port {DocsPort}", DocsDirectory);
+        });
+
+    Target DocsBuild => _ => _
+        .Executes(() =>
+        {
+            EnsureDocsDependencies();
+            BuildDocsSite();
+        });
+}

docs/contributing/development.md

@@ -55,10 +55,12 @@ All build logic lives in `build/`. Workflows call these targets instead of raw `
 | **Build** | Restore | Build the solution |
 | **Test** | Build | Run tests with coverage (trx + Coverlet) |
 | **Pack** | Test | Pack NuGet packages (.nupkg + .snupkg) |
-| **Publish** | Restore | Publish the selected host for a given `--Host` and `--Runtime` |
+| **Publish** | Restore | Publish the selected host for a given `--PublishHost` and `--Runtime` |
 | **PackageApp** | Publish | Zip published output to `app-{host}-{runtime}.zip` |
 | **Format** | Restore | `dotnet format --verify-no-changes` |
 | **CoverageReport** | Test | Generate HTML + Cobertura coverage report |
+| **Doc** | DocsBuild | Clear any same-port docs server and start the docs dev server |
+| **DocsBuild** | — | Install docs dependencies when needed and run `vitepress build` |
 | **ShowVersion** | — | Print current `VersionPrefix` |
 | **UpdateVersion** | — | Bump patch or set `--VersionPrefix` explicitly |
 | **GenerateReleaseManifest** | Pack | Create `release-manifest.json` with SHA256 hashes |
@@ -68,8 +70,11 @@ All build logic lives in `build/`. Workflows call these targets instead of raw `
 ```bash
 ./build.sh Test                                   # Build + Test
 ./build.sh Pack                                   # Build + Test + Pack
-./build.sh Publish --Host web --Runtime linux-x64 --SelfContained  # Publish self-contained web host
+./build.sh Publish --PublishHost web --Runtime linux-x64 --SelfContained  # Publish self-contained web host
 ./build.sh CoverageReport                         # Generate coverage HTML
+./build.sh DocsBuild                              # Build the docs site
+./build.sh Doc                                    # Install docs deps, kill any existing server, and start docs dev server on port 5173
+./build.sh Doc --DocsPort 8080                    # Same on a custom port (Ctrl+C to stop)
 ./build.sh ShowVersion                            # Print version
 ./build.sh UpdateVersion                          # Patch bump (e.g. 0.2.0 → 0.2.1)
 ./build.sh UpdateVersion --VersionPrefix 1.0.0    # Set version explicitly
@@ -82,9 +87,10 @@ All build logic lives in `build/`. Workflows call these targets instead of raw `
 | `--Configuration` | `Debug` (local) / `Release` (CI) | Build configuration |
 | `--VersionPrefix` | — | Version to set (used by `UpdateVersion`) |
 | `--VersionSuffix` | — | Prerelease suffix (e.g. `ci.42`) |
-| `--Host` | — | Host to publish (`web` or `cli`) |
+| `--PublishHost` | — | Host to publish (`web` or `cli`) |
 | `--Runtime` | — | Target RID for `Publish` (e.g. `linux-x64`) |
 | `--SelfContained` | `false` | Produce self-contained output |
+| `--DocsPort` | `5173` | Port used by `Doc` |
 
 ### Artifacts
 
@@ -106,6 +112,9 @@ npm install
 npm run docs:dev      # Local dev server at http://localhost:5173
 npm run docs:build    # Production build
 npm run docs:preview  # Preview production build
+
+# Or use NUKE from the repository root (blocks until Ctrl+C)
+build.ps1 Doc
 ```
 
 ## Next Steps

docs/package-lock.json

@@ -3,10 +3,12 @@
   "type": "module",
   "scripts": {
     "docs:dev": "vitepress dev",
+    "docs:dev:restart": "node ./scripts/docs-dev-restart.mjs",
     "docs:build": "vitepress build",
     "docs:preview": "vitepress preview"
   },
   "devDependencies": {
+    "kill-port": "^2.0.1",
     "vitepress": "^1.6.3"
   }
 }

docs/package.json

@@ -179,11 +179,18 @@ First full application bounded context for user management.
 | Type | Description |
 |---|---|
 | `IdentityModule` | Registers the Identity application services on top of the core runtime module. |
+| `RoleRecord` | Immutable role snapshot exposed through application contracts. |
 | `UserRecord` | Immutable user snapshot exposed through application contracts. |
+| `IRoleReader` | Reads roles by id, name, or ordered list. |
+| `IRoleManager` | Creates, updates, and removes roles while enforcing unique role-name rules. |
 | `IUserReader` | Reads users by id, user name, email, or ordered list. |
-| `IUserManager` | Creates, updates, and removes users while enforcing unique user name and email rules. |
+| `IUserManager` | Creates, updates, removes users, and manages their role assignments while enforcing unique user name and email rules. |
+| `IdentityRole` | Aggregate root for roles with normalized name and soft-delete behavior. |
 | `IdentityUser` | Aggregate root for users with normalized user name and email plus soft-delete behavior. |
+| `IdentityUserRole` | Domain-owned assignment record that keeps user-role membership inside the Identity model. |
+| `IIdentityRoleRepository` | Domain repository contract for identity-role lookup and persistence. |
 | `IIdentityUserRepository` | Domain repository contract for identity-user lookup and persistence. |
+| `RoleManager` | Application service that coordinates role uniqueness, lifecycle, and assignment cleanup. |
 | `UserManager` | Application service that coordinates uniqueness checks and persistence. |
 
 ### `ChengYuan.Identity.Persistence`
@@ -196,11 +203,25 @@ Persistence facet for identity-user storage backed by EF Core.
 |---|---|
 | `IdentityPersistenceModule` | Registers the EF-backed identity-user repository on top of the Identity application module. |
 | `IdentityDbContext` | Independent module DbContext for identity-user tables within the shared physical database. |
+| `IdentityRoleConfiguration` | EF Core model configuration for the identity-role aggregate. |
 | `IdentityUserConfiguration` | EF Core model configuration for the identity-user aggregate. |
+| `IdentityUserRoleConfiguration` | EF Core model configuration for the user-role assignment table. |
+| `EfIdentityRoleRepository` | EF Core implementation of `IIdentityRoleRepository`. |
 | `EfIdentityUserRepository` | EF Core implementation of `IIdentityUserRepository`. |
 | `AddIdentityDbContext()` | Registers the module DbContext against a caller-provided provider and connection. |
 | `AddIdentityPersistence()` | Registers the EF-backed identity repository and unit of work services. |
 
+### `ChengYuan.Identity.Web`
+
+Minimal HTTP management facet for Identity.
+
+#### Key Types
+
+| Type | Description |
+|---|---|
+| `IdentityWebModule` | Registers the Identity Web facet on top of the Identity application module. |
+| `MapIdentityManagementEndpoints()` | Maps the minimal HTTP management surface for users, roles, and user-role assignment operations. |
+
 ### `ChengYuan.Authorization`
 
 Definition-driven runtime permission checking.