# Management Service + CLI Implementation Plan

> **For Claude:** REQUIRED SUB-SKILL: Use superpowers-extended-cc:executing-plans to implement this plan task-by-task.

**Goal:** Add a ManagementService component (Akka.NET actor on Central exposing all admin operations via ClusterClientReceptionist) and a CLI tool (console app using ClusterClient) for scripting.

**Architecture:** ManagementActor is a cluster singleton on Central that receives typed command/response messages and delegates to the same services/repositories the Central UI uses. The CLI creates a minimal ActorSystem, connects via ClusterClient, authenticates via LDAP, and sends management commands. Message contracts live in Commons.

**Tech Stack:** C# / .NET 10, Akka.NET 1.5.62 (Cluster.Tools for ClusterClient/Receptionist), System.CommandLine, xUnit + NSubstitute

---

### Task 1: Create ManagementService project and test project

**Files:**
- Create: `src/ZB.MOM.WW.ScadaBridge.ManagementService/ZB.MOM.WW.ScadaBridge.ManagementService.csproj`
- Create: `src/ZB.MOM.WW.ScadaBridge.ManagementService/ServiceCollectionExtensions.cs`
- Create: `src/ZB.MOM.WW.ScadaBridge.ManagementService/ManagementServiceOptions.cs`
- Create: `tests/ZB.MOM.WW.ScadaBridge.ManagementService.Tests/ZB.MOM.WW.ScadaBridge.ManagementService.Tests.csproj`
- Modify: `ZB.MOM.WW.ScadaBridge.slnx` — add both projects

**Step 1:** Create the csproj following the existing pattern (net10.0, TreatWarningsAsErrors, ImplicitUsings). Reference Commons plus all service component projects needed: TemplateEngine, DeploymentManager, Communication, ExternalSystemGateway, NotificationService, Security, HealthMonitoring. Add Akka.Cluster.Tools 1.5.62.

**Step 2:** Create `ServiceCollectionExtensions.cs` with `AddManagementService()` — register `ManagementServiceOptions` binding. Create empty `ManagementServiceOptions.cs`.

**Step 3:** Create the test project csproj (xUnit, NSubstitute, reference ManagementService + Commons).

**Step 4:** Add both projects to `ZB.MOM.WW.ScadaBridge.slnx`.

**Step 5:** Build: `dotnet build ZB.MOM.WW.ScadaBridge.slnx`

**Step 6:** Commit: `feat: scaffold ManagementService project and test project`

---

### Task 2: Define management message contracts in Commons

**Files:**
- Create: `src/ZB.MOM.WW.ScadaBridge.Commons/Messages/Management/ManagementEnvelope.cs`
- Create: `src/ZB.MOM.WW.ScadaBridge.Commons/Messages/Management/ManagementResponse.cs`
- Create: `src/ZB.MOM.WW.ScadaBridge.Commons/Messages/Management/TemplateCommands.cs`
- Create: `src/ZB.MOM.WW.ScadaBridge.Commons/Messages/Management/InstanceCommands.cs`
- Create: `src/ZB.MOM.WW.ScadaBridge.Commons/Messages/Management/SiteCommands.cs`
- Create: `src/ZB.MOM.WW.ScadaBridge.Commons/Messages/Management/DataConnectionCommands.cs`
- Create: `src/ZB.MOM.WW.ScadaBridge.Commons/Messages/Management/DeploymentCommands.cs`
- Create: `src/ZB.MOM.WW.ScadaBridge.Commons/Messages/Management/ExternalSystemCommands.cs`
- Create: `src/ZB.MOM.WW.ScadaBridge.Commons/Messages/Management/NotificationCommands.cs`
- Create: `src/ZB.MOM.WW.ScadaBridge.Commons/Messages/Management/SecurityCommands.cs`
- Create: `src/ZB.MOM.WW.ScadaBridge.Commons/Messages/Management/AuditLogCommands.cs`
- Create: `src/ZB.MOM.WW.ScadaBridge.Commons/Messages/Management/HealthCommands.cs`

**Step 1:** Create `ManagementEnvelope.cs` — wrapper record carrying `AuthenticatedUser` (username, displayName, roles, permittedSiteIds) and the inner command:
```csharp
public record AuthenticatedUser(string Username, string DisplayName, IReadOnlyList<string> Roles, IReadOnlyList<string> PermittedSiteIds);
public record ManagementEnvelope(AuthenticatedUser User, object Command, string CorrelationId);
```

**Step 2:** Create `ManagementResponse.cs` — base response types:
```csharp
public record ManagementSuccess(string CorrelationId, object? Data);
public record ManagementError(string CorrelationId, string Error, string ErrorCode);
public record ManagementUnauthorized(string CorrelationId, string Message);
```

**Step 3:** Create all command/response files. Each file contains records for one domain area. Follow the additive-only evolution convention. Examples:
- `TemplateCommands.cs`: `ListTemplatesCommand`, `ListTemplatesResponse`, `GetTemplateCommand`, `GetTemplateResponse`, `CreateTemplateCommand`, `UpdateTemplateCommand`, `DeleteTemplateCommand`
- `InstanceCommands.cs`: `ListInstancesCommand(int? SiteId, int? TemplateId)`, `CreateInstanceCommand(string Name, int TemplateId, int SiteId)`, `DeployInstanceCommand(int InstanceId)`, `EnableInstanceCommand(int InstanceId)`, etc.
- Continue for all 10 message groups from the component doc.

**Step 4:** Build: `dotnet build ZB.MOM.WW.ScadaBridge.slnx`

**Step 5:** Commit: `feat: define management message contracts in Commons`

---

### Task 3: Implement ManagementActor

**Files:**
- Create: `src/ZB.MOM.WW.ScadaBridge.ManagementService/ManagementActor.cs`

**Step 1:** Create `ManagementActor` extending `ReceiveActor`. Constructor takes `IServiceProvider` (to resolve scoped services per request). Register `Receive<ManagementEnvelope>` handler.

**Step 2:** The envelope handler:
1. Extracts `AuthenticatedUser` and inner command
2. Checks authorization based on command type → required role
3. Creates a DI scope, resolves the needed service
4. Delegates to a private handler method per command type
5. Replies with `ManagementSuccess`, `ManagementError`, or `ManagementUnauthorized`

**Step 3:** Implement handler methods for each command group. Each handler follows the same pattern — resolve service from scope, call the existing service method, wrap result in response. Start with Templates and Instances as they're the most exercised.

**Step 4:** Build: `dotnet build ZB.MOM.WW.ScadaBridge.slnx`

**Step 5:** Commit: `feat: implement ManagementActor with all command handlers`

---

### Task 4: Register ManagementActor on Central and set up ClusterClientReceptionist

**Files:**
- Modify: `src/ZB.MOM.WW.ScadaBridge.Host/Actors/AkkaHostedService.cs` — RegisterCentralActors
- Modify: `src/ZB.MOM.WW.ScadaBridge.Host/Program.cs` — Central role, add `services.AddManagementService()`
- Modify: `src/ZB.MOM.WW.ScadaBridge.ManagementService/ServiceCollectionExtensions.cs` — ensure DI is wired

**Step 1:** In `RegisterCentralActors()`, after creating CentralCommunicationActor:
```csharp
// Management Service — ClusterClient accessible
var mgmtActor = _actorSystem!.ActorOf(
    Props.Create(() => new ManagementActor(_serviceProvider)),
    "management");
ClusterClientReceptionist.Get(_actorSystem).RegisterService(mgmtActor);
_logger.LogInformation("ManagementActor registered with ClusterClientReceptionist");
```

**Step 2:** In `Program.cs` Central role, add `builder.Services.AddManagementService()`.

**Step 3:** Build and verify Central starts with ManagementActor logged.

**Step 4:** Commit: `feat: register ManagementActor on Central with ClusterClientReceptionist`

---

### Task 5: Create CLI project with System.CommandLine scaffolding

**Files:**
- Create: `src/ZB.MOM.WW.ScadaBridge.CLI/ZB.MOM.WW.ScadaBridge.CLI.csproj`
- Create: `src/ZB.MOM.WW.ScadaBridge.CLI/Program.cs`
- Create: `src/ZB.MOM.WW.ScadaBridge.CLI/CliConfig.cs`
- Create: `src/ZB.MOM.WW.ScadaBridge.CLI/ClusterConnection.cs`
- Modify: `ZB.MOM.WW.ScadaBridge.slnx` — add CLI project

**Step 1:** Create csproj as console app. Reference Commons (for messages), Akka + Akka.Remote + Akka.Cluster.Tools (for ClusterClient), System.CommandLine, Novell.Directory.Ldap.NETStandard (for LDAP auth — same lib used by Security component).

**Step 2:** Create `CliConfig.cs` — reads config from env vars, `~/.scadabridge/config.json`, and CLI options. Properties: ContactPoints, LdapServer, LdapPort, LdapUseTls, DefaultFormat.

**Step 3:** Create `ClusterConnection.cs` — manages the ActorSystem and ClusterClient lifecycle:
```csharp
public class ClusterConnection : IAsyncDisposable
{
    public async Task ConnectAsync(IReadOnlyList<string> contactPoints);
    public async Task<object> AskManagementAsync(ManagementEnvelope envelope, TimeSpan timeout);
    public async ValueTask DisposeAsync();
}
```

**Step 4:** Create `Program.cs` with root command, global options (`--contact-points`, `--username`, `--password`, `--format`), and placeholder subcommands. Wire up LDAP auth flow in the root handler.

**Step 5:** Add to `ZB.MOM.WW.ScadaBridge.slnx`. Build: `dotnet build ZB.MOM.WW.ScadaBridge.slnx`.

**Step 6:** Commit: `feat: scaffold CLI project with ClusterClient connection`

---

### Task 6: Implement CLI command groups

**Files:**
- Create: `src/ZB.MOM.WW.ScadaBridge.CLI/Commands/TemplateCommands.cs`
- Create: `src/ZB.MOM.WW.ScadaBridge.CLI/Commands/InstanceCommands.cs`
- Create: `src/ZB.MOM.WW.ScadaBridge.CLI/Commands/SiteCommands.cs`
- Create: `src/ZB.MOM.WW.ScadaBridge.CLI/Commands/DeployCommands.cs`
- Create: `src/ZB.MOM.WW.ScadaBridge.CLI/Commands/DataConnectionCommands.cs`
- Create: `src/ZB.MOM.WW.ScadaBridge.CLI/Commands/ExternalSystemCommands.cs`
- Create: `src/ZB.MOM.WW.ScadaBridge.CLI/Commands/NotificationCommands.cs`
- Create: `src/ZB.MOM.WW.ScadaBridge.CLI/Commands/SecurityCommands.cs`
- Create: `src/ZB.MOM.WW.ScadaBridge.CLI/Commands/AuditLogCommands.cs`
- Create: `src/ZB.MOM.WW.ScadaBridge.CLI/Commands/HealthCommands.cs`
- Create: `src/ZB.MOM.WW.ScadaBridge.CLI/OutputFormatter.cs`

**Step 1:** Create `OutputFormatter.cs` — handles JSON and table output:
```csharp
public static class OutputFormatter
{
    public static void WriteJson(object data);
    public static void WriteTable(IEnumerable<object> rows, string[] columns);
    public static void WriteError(string message, string code);
}
```

**Step 2:** Implement each command group file. Each follows the same pattern:
- Define a `Command` with subcommands using System.CommandLine
- Each subcommand handler: build the typed command record, wrap in ManagementEnvelope with auth user, call `ClusterConnection.AskManagementAsync`, format output

**Step 3:** Register all command groups in Program.cs root command.

**Step 4:** Build: `dotnet build ZB.MOM.WW.ScadaBridge.slnx`

**Step 5:** Commit: `feat: implement all CLI command groups`

---

### Task 7: Write ManagementActor unit tests

**Files:**
- Create: `tests/ZB.MOM.WW.ScadaBridge.ManagementService.Tests/ManagementActorTests.cs`

**Step 1:** Test authorization enforcement — send commands without required role, verify `ManagementUnauthorized` response.

**Step 2:** Test template operations — mock `ITemplateEngineRepository`, send `ListTemplatesCommand`, verify response contains expected data.

**Step 3:** Test instance operations — mock services, send `CreateInstanceCommand`, verify delegation.

**Step 4:** Run tests: `dotnet test tests/ZB.MOM.WW.ScadaBridge.ManagementService.Tests/`

**Step 5:** Commit: `test: add ManagementActor unit tests`

---

### Task 8: End-to-end integration test

**Step 1:** Start Central with ManagementActor registered. Verify log shows "ManagementActor registered with ClusterClientReceptionist".

**Step 2:** Run CLI: `dotnet run --project src/ZB.MOM.WW.ScadaBridge.CLI -- --contact-points akka.tcp://scadabridge@localhost:8081 --username admin --password password template list`

**Step 3:** Verify CLI connects, authenticates, sends command, receives response, prints templates.

**Step 4:** Test error cases: wrong password (exit code 2), unauthorized role (exit code 3), unreachable host (exit code 4).

**Step 5:** Commit any fixes.
