using System.Collections.Immutable;

namespace StellaOps.Doctor.Models;

/// <summary>
/// A single step in a remediation workflow.
/// </summary>
public sealed record RemediationStep
{
    /// <summary>
    /// Order of this step in the remediation sequence (1-based).
    /// </summary>
    public required int Order { get; init; }

    /// <summary>
    /// Human-readable description of what this step does.
    /// </summary>
    public required string Description { get; init; }

    /// <summary>
    /// The command or action to execute.
    /// May contain placeholders like {HOSTNAME} or {PASSWORD}.
    /// </summary>
    public required string Command { get; init; }

    /// <summary>
    /// Type of command (shell, SQL, API, etc.).
    /// </summary>
    public CommandType CommandType { get; init; } = CommandType.Shell;

    /// <summary>
    /// Placeholders in the command that need user-supplied values.
    /// Key is the placeholder name (e.g., "HOSTNAME"), value is the description.
    /// </summary>
    public IReadOnlyDictionary<string, string>? Placeholders { get; init; }

    /// <summary>
    /// Indicates if this step performs destructive operations (delete, truncate, drop, reset, etc.).
    /// Destructive steps should not be auto-executed by AdvisoryAI.
    /// Added as part of SPRINT_20260118_015_Doctor_check_quality_improvements (DQUAL-005).
    /// </summary>
    public bool IsDestructive { get; init; }

    /// <summary>
    /// A safe dry-run variant of the command that previews what would happen without making changes.
    /// For example, "rm -rf /path" might have a dry-run variant of "find /path -type f | head -20".
    /// Added as part of SPRINT_20260118_015_Doctor_check_quality_improvements (DQUAL-005).
    /// </summary>
    public string? DryRunVariant { get; init; }
}

/// <summary>
/// Remediation instructions for fixing a failed check.
/// </summary>
public sealed record Remediation
{
    /// <summary>
    /// Ordered steps to remediate the issue.
    /// </summary>
    public required IReadOnlyList<RemediationStep> Steps { get; init; }

    /// <summary>
    /// Safety note about the remediation (e.g., "This will restart the service").
    /// </summary>
    public string? SafetyNote { get; init; }

    /// <summary>
    /// Whether a backup is recommended before applying remediation.
    /// </summary>
    public bool RequiresBackup { get; init; }

    /// <summary>
    /// URL to a detailed runbook for this remediation.
    /// Added as part of SPRINT_20260117_029_DOCS_runbook_coverage (RUN-008).
    /// </summary>
    public string? RunbookUrl { get; init; }

    /// <summary>
    /// Creates an empty remediation with no steps.
    /// </summary>
    public static Remediation Empty => new()
    {
        Steps = ImmutableArray<RemediationStep>.Empty
    };
}