old sprints work, new sprints for exposing functionality via cli, improve code_of_conduct and other agents instructions
This commit is contained in:
master
@@ -0,0 +1,372 @@
|
||||
// Copyright (c) StellaOps. All rights reserved.
|
||||
// Licensed under AGPL-3.0-or-later. 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.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 alerts and notifications (optional).</summary>
|
||||
Notifications = 8,
|
||||
|
||||
/// <summary>Define deployment environments (optional).</summary>
|
||||
Environments = 9,
|
||||
|
||||
/// <summary>Register deployment agents (optional).</summary>
|
||||
Agents = 10
|
||||
}
|
||||
|
||||
/// <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.Notifications,
|
||||
Title: "Notification Channels",
|
||||
Subtitle: "Configure alerts and notifications",
|
||||
OrderIndex: 8,
|
||||
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: 9,
|
||||
IsRequired: false,
|
||||
DependsOn: ImmutableArray.Create(SetupStepId.Admin),
|
||||
DoctorChecks: ImmutableArray<string>.Empty),
|
||||
|
||||
new SetupStepDefinition(
|
||||
Id: SetupStepId.Agents,
|
||||
Title: "Agent Registration",
|
||||
Subtitle: "Register deployment agents",
|
||||
OrderIndex: 10,
|
||||
IsRequired: false,
|
||||
DependsOn: ImmutableArray.Create(SetupStepId.Environments),
|
||||
DoctorChecks: ImmutableArray<string>.Empty)
|
||||
);
|
||||
|
||||
/// <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);
|
||||
|
||||
#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
|
||||
Reference in New Issue
Block a user