w4c-workflows-api/Services/WorkflowSource.cs

namespace w4c_workflows.Services;

/// <summary>A workflow definition file discovered in the git source.</summary>
public sealed record WorkflowFile(string Path);

/// <summary>Current git state of the workflow source (for "sync status vs git").</summary>
public sealed record WorkflowSourceState(string? HeadSha, bool Dirty);

/// <summary>
/// Reads workflow YAML definitions from the tenant's authoritative source. In
/// Forgejo-backed mode this is a local clone of the tenant's private repo; in
/// filesystem-only mode it is the tenant directory under
/// <c>WorkflowSource:CopiesRoot</c>. See <see cref="WorkflowSourceFactory"/> for
/// the two modes and <see cref="PerTenantWorkflowSource"/> for the implementation.
/// </summary>
public interface IWorkflowSource
{
    Task<IReadOnlyList<WorkflowFile>> ListAsync(CancellationToken ct);
    Task<string> ReadAsync(string path, CancellationToken ct);

    /// <summary>
    /// HEAD sha + dirty flag of the backing working tree. Backed by
    /// <see cref="GitRunner.GetStateAsync"/> (one cached git call), so it is safe
    /// to call from a per-request listing.
    /// </summary>
    Task<WorkflowSourceState> GetStateAsync(CancellationToken ct = default);
}