diff --git a/src/coordination/index.ts b/src/coordination/index.ts new file mode 100644 index 0000000..ac31679 --- /dev/null +++ b/src/coordination/index.ts @@ -0,0 +1,23 @@ +/** + * Coordination Module - Public API + * + * Exports the CoordinationManager port interface and related types. + * All modules should import from this index file. + * + * Port-Adapter Pattern: + * - CoordinationManager is the PORT (interface contract) + * - Implementations (e.g., InMemoryCoordinationManager) are ADAPTERS + * - Consumers depend only on the port interface + * - Adapters can be swapped without changing consumer code + * + * This enables: + * - Testing with mock/in-memory implementations + * - Future swapping to persistent/distributed implementations + * - Clean separation between domain logic and infrastructure + */ + +// Port interface (what consumers depend on) +export type { CoordinationManager } from './types.js'; + +// Domain types +export type { MergeQueueItem, MergeStatus, MergeResult } from './types.js'; diff --git a/src/coordination/types.ts b/src/coordination/types.ts new file mode 100644 index 0000000..a9e92fc --- /dev/null +++ b/src/coordination/types.ts @@ -0,0 +1,129 @@ +/** + * 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; + + /** + * 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; + + /** + * 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; + + /** + * 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; + + /** + * 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[] }>; + }>; +}