namespace AxCopilot.SDK;

/// <summary>
/// AX Copilot 플러그인이 구현해야 하는 핵심 인터페이스.
/// 새로운 명령어 타입을 추가하려면 이 인터페이스를 구현하고
/// settings.json의 "plugins" 배열에 .dll 경로를 등록하십시오.
/// </summary>
public interface IActionHandler
{
    /// <summary>
    /// 이 핸들러를 트리거하는 prefix 문자 (예: "@", "!", "#", "~", ">", "$").
    /// null이면 prefix 없이 Fuzzy 검색 결과에만 항목을 제공합니다.
    /// </summary>
    string? Prefix { get; }

    /// <summary>
    /// 플러그인 메타데이터
    /// </summary>
    PluginMetadata Metadata { get; }

    /// <summary>
    /// 런처 결과 리스트에 표시할 항목을 반환합니다.
    /// </summary>
    /// <param name="query">prefix 이후의 사용자 입력 텍스트</param>
    /// <param name="ct">ESC 입력 시 취소되는 CancellationToken</param>
    Task<IEnumerable<LauncherItem>> GetItemsAsync(string query, CancellationToken ct);

    /// <summary>
    /// 사용자가 항목을 선택(Enter)했을 때 실행되는 동작
    /// </summary>
    Task ExecuteAsync(LauncherItem item, CancellationToken ct);
}

/// <summary>
/// 런처 결과 리스트에 표시될 단일 항목
/// </summary>
public record LauncherItem(
    string Title,
    string Subtitle,
    string? IconPath,           // null이면 기본 아이콘 사용
    object? Data,               // ExecuteAsync에 전달되는 임의 데이터
    string? ActionUrl = null,   // Enter 시 열릴 URL (선택)
    string? Symbol = null       // Segoe MDL2 Assets 유니코드 심볼 (null이면 타입 기반 자동 결정)
);

/// <summary>
/// 플러그인 식별 메타데이터
/// </summary>
public record PluginMetadata(
    string Id,
    string Name,
    string Version,
    string Author,
    string? Description = null
);