// 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