449 lines
13 KiB
C#
449 lines
13 KiB
C#
// Copyright (c) StellaOps. All rights reserved.
|
|
// Licensed under BUSL-1.1. See LICENSE in the project root.
|
|
// Sprint: SPRINT_20260112_004_PLATFORM_setup_wizard_backend (PLATFORM-SETUP-001)
|
|
// Task: Define setup wizard contracts and step definitions
|
|
|
|
using System.Collections.Generic;
|
|
using System.Collections.Immutable;
|
|
using System.Text.Json.Serialization;
|
|
|
|
namespace StellaOps.Platform.WebService.Contracts;
|
|
|
|
#region Enums
|
|
|
|
/// <summary>
|
|
/// Setup wizard step identifiers aligned to docs/setup/setup-wizard-ux.md.
|
|
/// </summary>
|
|
[JsonConverter(typeof(JsonStringEnumConverter))]
|
|
public enum SetupStepId
|
|
{
|
|
/// <summary>Configure PostgreSQL connection.</summary>
|
|
Database = 1,
|
|
|
|
/// <summary>Configure Valkey/Redis caching and message queue.</summary>
|
|
Valkey = 2,
|
|
|
|
/// <summary>Apply database schema migrations.</summary>
|
|
Migrations = 3,
|
|
|
|
/// <summary>Create administrator account.</summary>
|
|
Admin = 4,
|
|
|
|
/// <summary>Configure signing keys and crypto profile.</summary>
|
|
Crypto = 5,
|
|
|
|
/// <summary>Configure secrets management (optional).</summary>
|
|
Vault = 6,
|
|
|
|
/// <summary>Connect source control (optional).</summary>
|
|
Scm = 7,
|
|
|
|
/// <summary>Configure advisory data sources (optional).</summary>
|
|
Sources = 8,
|
|
|
|
/// <summary>Configure alerts and notifications (optional).</summary>
|
|
Notifications = 9,
|
|
|
|
/// <summary>Define deployment environments (optional).</summary>
|
|
Environments = 10,
|
|
|
|
/// <summary>Register deployment agents (optional).</summary>
|
|
Agents = 11,
|
|
|
|
/// <summary>Configure container registry (optional).</summary>
|
|
Registry = 12,
|
|
|
|
/// <summary>Configure OpenTelemetry (optional).</summary>
|
|
Telemetry = 13,
|
|
|
|
/// <summary>Configure AI/LLM provider for AdvisoryAI (optional).</summary>
|
|
Llm = 14,
|
|
|
|
/// <summary>Configure external settings store (optional).</summary>
|
|
SettingsStore = 15
|
|
}
|
|
|
|
/// <summary>
|
|
/// Setup step status aligned to docs/setup/setup-wizard-ux.md.
|
|
/// </summary>
|
|
[JsonConverter(typeof(JsonStringEnumConverter))]
|
|
public enum SetupStepStatus
|
|
{
|
|
/// <summary>Not yet started.</summary>
|
|
Pending,
|
|
|
|
/// <summary>Currently active step.</summary>
|
|
Current,
|
|
|
|
/// <summary>Completed successfully.</summary>
|
|
Passed,
|
|
|
|
/// <summary>Failed validation.</summary>
|
|
Failed,
|
|
|
|
/// <summary>Explicitly skipped by user.</summary>
|
|
Skipped,
|
|
|
|
/// <summary>Blocked by failed dependency.</summary>
|
|
Blocked
|
|
}
|
|
|
|
/// <summary>
|
|
/// Overall setup session status.
|
|
/// </summary>
|
|
[JsonConverter(typeof(JsonStringEnumConverter))]
|
|
public enum SetupSessionStatus
|
|
{
|
|
/// <summary>Setup not started.</summary>
|
|
NotStarted,
|
|
|
|
/// <summary>Setup in progress.</summary>
|
|
InProgress,
|
|
|
|
/// <summary>Setup completed successfully.</summary>
|
|
Completed,
|
|
|
|
/// <summary>Setup completed with skipped optional steps.</summary>
|
|
CompletedPartial,
|
|
|
|
/// <summary>Setup failed due to required step failure.</summary>
|
|
Failed,
|
|
|
|
/// <summary>Setup abandoned by user.</summary>
|
|
Abandoned
|
|
}
|
|
|
|
/// <summary>
|
|
/// Doctor check status for step validation.
|
|
/// </summary>
|
|
[JsonConverter(typeof(JsonStringEnumConverter))]
|
|
public enum SetupCheckStatus
|
|
{
|
|
/// <summary>Check passed.</summary>
|
|
Pass,
|
|
|
|
/// <summary>Check failed.</summary>
|
|
Fail,
|
|
|
|
/// <summary>Check produced a warning.</summary>
|
|
Warn,
|
|
|
|
/// <summary>Check not executed.</summary>
|
|
NotRun
|
|
}
|
|
|
|
#endregion
|
|
|
|
#region Step Definitions
|
|
|
|
/// <summary>
|
|
/// Static definition of a setup wizard step.
|
|
/// </summary>
|
|
public sealed record SetupStepDefinition(
|
|
SetupStepId Id,
|
|
string Title,
|
|
string Subtitle,
|
|
int OrderIndex,
|
|
bool IsRequired,
|
|
ImmutableArray<SetupStepId> DependsOn,
|
|
ImmutableArray<string> DoctorChecks);
|
|
|
|
/// <summary>
|
|
/// Provides the canonical setup wizard step definitions.
|
|
/// </summary>
|
|
public static class SetupStepDefinitions
|
|
{
|
|
public static ImmutableArray<SetupStepDefinition> All { get; } = ImmutableArray.Create(
|
|
new SetupStepDefinition(
|
|
Id: SetupStepId.Database,
|
|
Title: "Database Setup",
|
|
Subtitle: "Configure PostgreSQL connection",
|
|
OrderIndex: 1,
|
|
IsRequired: true,
|
|
DependsOn: ImmutableArray<SetupStepId>.Empty,
|
|
DoctorChecks: ImmutableArray.Create(
|
|
"check.database.connectivity",
|
|
"check.database.permissions",
|
|
"check.database.version")),
|
|
|
|
new SetupStepDefinition(
|
|
Id: SetupStepId.Valkey,
|
|
Title: "Valkey/Redis Setup",
|
|
Subtitle: "Configure caching and message queue",
|
|
OrderIndex: 2,
|
|
IsRequired: true,
|
|
DependsOn: ImmutableArray<SetupStepId>.Empty,
|
|
DoctorChecks: ImmutableArray.Create(
|
|
"check.services.valkey.connectivity")),
|
|
|
|
new SetupStepDefinition(
|
|
Id: SetupStepId.Migrations,
|
|
Title: "Database Migrations",
|
|
Subtitle: "Apply schema updates",
|
|
OrderIndex: 3,
|
|
IsRequired: true,
|
|
DependsOn: ImmutableArray.Create(SetupStepId.Database),
|
|
DoctorChecks: ImmutableArray.Create(
|
|
"check.database.migrations.pending")),
|
|
|
|
new SetupStepDefinition(
|
|
Id: SetupStepId.Admin,
|
|
Title: "Admin Bootstrap",
|
|
Subtitle: "Create administrator account",
|
|
OrderIndex: 4,
|
|
IsRequired: true,
|
|
DependsOn: ImmutableArray.Create(SetupStepId.Migrations),
|
|
DoctorChecks: ImmutableArray.Create(
|
|
"check.authority.admin.exists")),
|
|
|
|
new SetupStepDefinition(
|
|
Id: SetupStepId.Crypto,
|
|
Title: "Crypto Profile",
|
|
Subtitle: "Configure signing keys",
|
|
OrderIndex: 5,
|
|
IsRequired: true,
|
|
DependsOn: ImmutableArray.Create(SetupStepId.Admin),
|
|
DoctorChecks: ImmutableArray.Create(
|
|
"check.crypto.signing.key",
|
|
"check.crypto.profile")),
|
|
|
|
new SetupStepDefinition(
|
|
Id: SetupStepId.Vault,
|
|
Title: "Vault Integration",
|
|
Subtitle: "Configure secrets management",
|
|
OrderIndex: 6,
|
|
IsRequired: false,
|
|
DependsOn: ImmutableArray<SetupStepId>.Empty,
|
|
DoctorChecks: ImmutableArray.Create(
|
|
"check.security.vault.connectivity")),
|
|
|
|
new SetupStepDefinition(
|
|
Id: SetupStepId.Scm,
|
|
Title: "SCM Integration",
|
|
Subtitle: "Connect source control",
|
|
OrderIndex: 7,
|
|
IsRequired: false,
|
|
DependsOn: ImmutableArray<SetupStepId>.Empty,
|
|
DoctorChecks: ImmutableArray.Create(
|
|
"check.integration.scm.github.auth",
|
|
"check.integration.scm.gitlab.auth",
|
|
"check.integration.scm.gitea.auth")),
|
|
|
|
new SetupStepDefinition(
|
|
Id: SetupStepId.Sources,
|
|
Title: "Advisory Sources",
|
|
Subtitle: "Configure CVE/advisory data sources",
|
|
OrderIndex: 8,
|
|
IsRequired: false,
|
|
DependsOn: ImmutableArray<SetupStepId>.Empty,
|
|
DoctorChecks: ImmutableArray.Create(
|
|
"check.sources.mode.configured",
|
|
"check.sources.nvd.connectivity",
|
|
"check.sources.ghsa.connectivity")),
|
|
|
|
new SetupStepDefinition(
|
|
Id: SetupStepId.Notifications,
|
|
Title: "Notification Channels",
|
|
Subtitle: "Configure alerts and notifications",
|
|
OrderIndex: 9,
|
|
IsRequired: false,
|
|
DependsOn: ImmutableArray<SetupStepId>.Empty,
|
|
DoctorChecks: ImmutableArray.Create(
|
|
"check.notify.email",
|
|
"check.notify.slack")),
|
|
|
|
new SetupStepDefinition(
|
|
Id: SetupStepId.Environments,
|
|
Title: "Environment Definition",
|
|
Subtitle: "Define deployment environments",
|
|
OrderIndex: 10,
|
|
IsRequired: false,
|
|
DependsOn: ImmutableArray.Create(SetupStepId.Admin),
|
|
DoctorChecks: ImmutableArray<string>.Empty),
|
|
|
|
new SetupStepDefinition(
|
|
Id: SetupStepId.Agents,
|
|
Title: "Agent Registration",
|
|
Subtitle: "Register deployment agents",
|
|
OrderIndex: 11,
|
|
IsRequired: false,
|
|
DependsOn: ImmutableArray.Create(SetupStepId.Environments),
|
|
DoctorChecks: ImmutableArray<string>.Empty),
|
|
|
|
new SetupStepDefinition(
|
|
Id: SetupStepId.Registry,
|
|
Title: "Container Registry",
|
|
Subtitle: "Configure container registry connections",
|
|
OrderIndex: 12,
|
|
IsRequired: false,
|
|
DependsOn: ImmutableArray<SetupStepId>.Empty,
|
|
DoctorChecks: ImmutableArray.Create(
|
|
"check.integration.registry.connectivity",
|
|
"check.integration.registry.auth")),
|
|
|
|
new SetupStepDefinition(
|
|
Id: SetupStepId.Telemetry,
|
|
Title: "Telemetry Setup",
|
|
Subtitle: "Configure OpenTelemetry for observability",
|
|
OrderIndex: 13,
|
|
IsRequired: false,
|
|
DependsOn: ImmutableArray<SetupStepId>.Empty,
|
|
DoctorChecks: ImmutableArray.Create(
|
|
"check.telemetry.otlp.connectivity")),
|
|
|
|
new SetupStepDefinition(
|
|
Id: SetupStepId.Llm,
|
|
Title: "AdvisoryAI Provider",
|
|
Subtitle: "Configure AI/LLM provider for intelligent triage",
|
|
OrderIndex: 14,
|
|
IsRequired: false,
|
|
DependsOn: ImmutableArray<SetupStepId>.Empty,
|
|
DoctorChecks: ImmutableArray.Create(
|
|
"check.llm.provider.connectivity",
|
|
"check.llm.model.available")),
|
|
|
|
new SetupStepDefinition(
|
|
Id: SetupStepId.SettingsStore,
|
|
Title: "Settings Store",
|
|
Subtitle: "Configure external configuration store",
|
|
OrderIndex: 15,
|
|
IsRequired: false,
|
|
DependsOn: ImmutableArray<SetupStepId>.Empty,
|
|
DoctorChecks: ImmutableArray.Create(
|
|
"check.settingsstore.connectivity"))
|
|
);
|
|
|
|
/// <summary>
|
|
/// Gets a step definition by ID.
|
|
/// </summary>
|
|
public static SetupStepDefinition? GetById(SetupStepId id)
|
|
{
|
|
foreach (var step in All)
|
|
{
|
|
if (step.Id == id) return step;
|
|
}
|
|
return null;
|
|
}
|
|
}
|
|
|
|
#endregion
|
|
|
|
#region Session State
|
|
|
|
/// <summary>
|
|
/// Setup wizard session state.
|
|
/// </summary>
|
|
public sealed record SetupSession(
|
|
string SessionId,
|
|
string TenantId,
|
|
SetupSessionStatus Status,
|
|
ImmutableArray<SetupStepState> Steps,
|
|
string CreatedAtUtc,
|
|
string UpdatedAtUtc,
|
|
string? CreatedBy,
|
|
string? UpdatedBy,
|
|
string? DataAsOfUtc);
|
|
|
|
/// <summary>
|
|
/// State of a single setup step within a session.
|
|
/// </summary>
|
|
public sealed record SetupStepState(
|
|
SetupStepId StepId,
|
|
SetupStepStatus Status,
|
|
string? CompletedAtUtc,
|
|
string? SkippedAtUtc,
|
|
string? SkippedReason,
|
|
ImmutableArray<SetupCheckResult> CheckResults,
|
|
string? ErrorMessage);
|
|
|
|
/// <summary>
|
|
/// Result of a Doctor check during step validation.
|
|
/// </summary>
|
|
public sealed record SetupCheckResult(
|
|
string CheckId,
|
|
SetupCheckStatus Status,
|
|
string? Message,
|
|
string? SuggestedFix);
|
|
|
|
#endregion
|
|
|
|
#region API Requests
|
|
|
|
/// <summary>
|
|
/// Request to create a new setup session.
|
|
/// </summary>
|
|
public sealed record CreateSetupSessionRequest(
|
|
string? TenantId = null);
|
|
|
|
/// <summary>
|
|
/// Request to execute a setup step.
|
|
/// </summary>
|
|
public sealed record ExecuteSetupStepRequest(
|
|
SetupStepId StepId,
|
|
ImmutableDictionary<string, string>? Configuration = null);
|
|
|
|
/// <summary>
|
|
/// Request to skip a setup step.
|
|
/// </summary>
|
|
public sealed record SkipSetupStepRequest(
|
|
SetupStepId StepId,
|
|
string? Reason = null);
|
|
|
|
/// <summary>
|
|
/// Request to finalize a setup session.
|
|
/// </summary>
|
|
public sealed record FinalizeSetupSessionRequest(
|
|
bool Force = false);
|
|
|
|
/// <summary>
|
|
/// Request to test connectivity for a setup step.
|
|
/// </summary>
|
|
public sealed record SetupTestConnectionRequest(
|
|
Dictionary<string, string>? ConfigValues = null);
|
|
|
|
#endregion
|
|
|
|
#region API Responses
|
|
|
|
/// <summary>
|
|
/// Response for setup session operations.
|
|
/// </summary>
|
|
public sealed record SetupSessionResponse(
|
|
SetupSession Session);
|
|
|
|
/// <summary>
|
|
/// Response for step execution.
|
|
/// </summary>
|
|
public sealed record ExecuteSetupStepResponse(
|
|
SetupStepState StepState,
|
|
bool Success,
|
|
string? ErrorMessage,
|
|
ImmutableArray<SetupSuggestedFix> SuggestedFixes);
|
|
|
|
/// <summary>
|
|
/// Response listing all step definitions.
|
|
/// </summary>
|
|
public sealed record SetupStepDefinitionsResponse(
|
|
ImmutableArray<SetupStepDefinition> Steps);
|
|
|
|
/// <summary>
|
|
/// A suggested fix for a failed step.
|
|
/// </summary>
|
|
public sealed record SetupSuggestedFix(
|
|
string Title,
|
|
string Description,
|
|
string? Command,
|
|
string? DocumentationUrl);
|
|
|
|
/// <summary>
|
|
/// Response for session finalization.
|
|
/// </summary>
|
|
public sealed record FinalizeSetupSessionResponse(
|
|
SetupSessionStatus FinalStatus,
|
|
ImmutableArray<SetupStepState> CompletedSteps,
|
|
ImmutableArray<SetupStepState> SkippedSteps,
|
|
ImmutableArray<SetupStepState> FailedSteps,
|
|
string? ReportPath);
|
|
|
|
#endregion
|