// -----------------------------------------------------------------------------
// IRebuildService.cs
// Sprint: SPRINT_20260119_005 Reproducible Rebuild Integration
// Task: REPR-001 - Rebuild Service Abstractions
// Description: Main interface for reproducible rebuild orchestration.
// -----------------------------------------------------------------------------

namespace StellaOps.BinaryIndex.GroundTruth.Reproducible;

/// <summary>
/// Service for orchestrating reproducible binary rebuilds.
/// </summary>
public interface IRebuildService
{
    /// <summary>
    /// Requests a rebuild for a package.
    /// </summary>
    /// <param name="request">The rebuild request.</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    /// <returns>The rebuild job ID.</returns>
    Task<string> RequestRebuildAsync(
        RebuildRequest request,
        CancellationToken cancellationToken = default);

    /// <summary>
    /// Gets the status of a rebuild job.
    /// </summary>
    /// <param name="jobId">The job ID.</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    /// <returns>The rebuild status.</returns>
    Task<RebuildStatus> GetStatusAsync(
        string jobId,
        CancellationToken cancellationToken = default);

    /// <summary>
    /// Downloads the artifacts from a completed rebuild.
    /// </summary>
    /// <param name="jobId">The job ID.</param>
    /// <param name="outputDirectory">The directory to write artifacts.</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    /// <returns>The rebuild result with artifacts.</returns>
    Task<RebuildResult> DownloadArtifactsAsync(
        string jobId,
        string outputDirectory,
        CancellationToken cancellationToken = default);

    /// <summary>
    /// Performs a local rebuild using a .buildinfo file.
    /// </summary>
    /// <param name="buildinfoPath">Path to the .buildinfo file.</param>
    /// <param name="options">Local rebuild options.</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    /// <returns>The rebuild result.</returns>
    Task<RebuildResult> RebuildLocalAsync(
        string buildinfoPath,
        LocalRebuildOptions? options = null,
        CancellationToken cancellationToken = default);

    /// <summary>
    /// Queries if a package has existing rebuild data.
    /// </summary>
    /// <param name="package">Package name.</param>
    /// <param name="version">Package version.</param>
    /// <param name="architecture">Target architecture.</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    /// <returns>Existing rebuild info if available.</returns>
    Task<RebuildInfo?> QueryExistingRebuildAsync(
        string package,
        string version,
        string architecture,
        CancellationToken cancellationToken = default);
}

/// <summary>
/// Rebuild backend type.
/// </summary>
public enum RebuildBackend
{
    /// <summary>
    /// Remote rebuild via reproduce.debian.net.
    /// </summary>
    ReproduceDebian,

    /// <summary>
    /// Local container-based rebuild.
    /// </summary>
    Local,

    /// <summary>
    /// Air-gapped rebuild from pre-fetched bundle.
    /// </summary>
    AirGap
}