/**
 * Coordination Module Types
 *
 * Port interface for merge coordination management.
 * CoordinationManager is the PORT. Implementations are ADAPTERS.
 *
 * This follows the same hexagonal architecture pattern as EventBus, AgentManager, and DispatchManager:
 * - Interface defines the contract (port)
 * - Implementations can be swapped without changing consumers
 * - Enables testing with in-memory/mock implementations
 */

// =============================================================================
// Coordination Domain Types
// =============================================================================

/**
 * Represents a task queued for merge.
 * Tasks are queued after completion and merged in dependency order.
 */
export interface MergeQueueItem {
  /** ID of the task to merge */
  taskId: string;
  /** ID of the agent that completed the task */
  agentId: string;
  /** ID of the worktree containing the changes */
  worktreeId: string;
  /** Priority level for merge ordering */
  priority: 'low' | 'medium' | 'high';
  /** When the task was queued for merge */
  queuedAt: Date;
  /** Task IDs that must merge first (dependency ordering) */
  dependsOn: string[];
}

/**
 * Status of a merge operation.
 */
export type MergeStatus = 'queued' | 'in_progress' | 'merged' | 'conflict';

/**
 * Result of a merge operation with task context.
 * Mirrors git MergeResult but includes task-level information.
 */
export interface MergeResult {
  /** ID of the task that was merged */
  taskId: string;
  /** True if merge completed without conflicts */
  success: boolean;
  /** List of conflicting files (only present if success is false) */
  conflicts?: string[];
  /** Human-readable message describing the result */
  message: string;
}

// =============================================================================
// CoordinationManager Port Interface
// =============================================================================

/**
 * CoordinationManager Port Interface
 *
 * Manages merge coordination for completed tasks.
 * Ensures merges happen in dependency order and handles conflicts.
 *
 * This is the PORT - implementations (adapters) include:
 * - InMemoryCoordinationManager: In-memory for testing
 * - (future) PersistentCoordinationManager: Database-backed
 *
 * Covers requirements:
 * - COORD-01: Queue completed tasks for merge
 * - COORD-02: Get next mergeable task (dependencies resolved)
 * - COORD-03: Process merges in dependency order
 * - COORD-04: Handle conflicts (bounce-back to agent)
 * - COORD-05: Track queue state
 */
export interface CoordinationManager {
  /**
   * Queue a completed task for merge.
   * Extracts agent/worktree information from the task.
   *
   * @param taskId - ID of the completed task to queue
   */
  queueMerge(taskId: string): Promise<void>;

  /**
   * Get next task ready to merge.
   * Returns task with all dependency tasks already merged.
   * Returns null if no tasks ready.
   *
   * @returns Next mergeable task or null
   */
  getNextMergeable(): Promise<MergeQueueItem | null>;

  /**
   * Process all ready merges in dependency order.
   * Merges each ready task into the target branch.
   *
   * @param targetBranch - Branch to merge into (e.g., 'main', 'integration')
   * @returns Results of all merge operations
   */
  processMerges(targetBranch: string): Promise<MergeResult[]>;

  /**
   * Handle a merge conflict.
   * Creates a conflict-resolution task and assigns back to the agent.
   *
   * @param taskId - ID of the task that conflicted
   * @param conflicts - List of conflicting file paths
   */
  handleConflict(taskId: string, conflicts: string[]): Promise<void>;

  /**
   * Get current state of the merge queue.
   * Shows all tasks by their merge status.
   *
   * @returns Queue state grouped by status
   */
  getQueueState(): Promise<{
    /** Tasks waiting to be merged */
    queued: MergeQueueItem[];
    /** Tasks currently being merged */
    inProgress: MergeQueueItem[];
    /** Task IDs that have been merged */
    merged: string[];
    /** Tasks with conflicts awaiting resolution */
    conflicted: Array<{ taskId: string; conflicts: string[] }>;
  }>;
}
