diff --git a/src/git/index.ts b/src/git/index.ts new file mode 100644 index 0000000..c53c6ed --- /dev/null +++ b/src/git/index.ts @@ -0,0 +1,16 @@ +/** + * Git Module - Public API + * + * Exports the WorktreeManager port interface and types. + * All modules should import from this index file. + * + * Pattern follows EventBus module: + * - Port interface (WorktreeManager) is what consumers depend on + * - Adapter implementations will be added in future plans + */ + +// Port interface (what consumers depend on) +export type { WorktreeManager } from './types.js'; + +// Domain types +export type { Worktree, WorktreeDiff, MergeResult } from './types.js'; diff --git a/src/git/types.ts b/src/git/types.ts new file mode 100644 index 0000000..3a94117 --- /dev/null +++ b/src/git/types.ts @@ -0,0 +1,149 @@ +/** + * Git Module Types + * + * Port interface for git worktree operations. + * WorktreeManager is the PORT. Implementations (GitWorktreeManager, MockWorktreeManager) are ADAPTERS. + * + * This follows the same hexagonal architecture pattern as EventBus: + * - Interface defines the contract (port) + * - Implementations can be swapped without changing consumers + * - Enables testing with in-memory/mock implementations + */ + +// ============================================================================= +// Worktree Domain Types +// ============================================================================= + +/** + * Represents a git worktree - an isolated working directory + * that shares the same git repository but has its own branch. + */ +export interface Worktree { + /** Unique identifier for this worktree */ + id: string; + /** Branch name checked out in this worktree */ + branch: string; + /** Absolute path to the worktree directory */ + path: string; + /** True if this is the main worktree (the original checkout) */ + isMainWorktree: boolean; +} + +/** + * Represents the diff/changes in a worktree compared to its base. + * Used for previewing what will be merged. + */ +export interface WorktreeDiff { + /** List of files with changes */ + files: Array<{ + /** Relative path to the file */ + path: string; + /** Type of change */ + status: 'added' | 'modified' | 'deleted'; + }>; + /** Human-readable summary of changes (e.g., "3 files changed, 45 insertions") */ + summary: string; +} + +/** + * Result of a merge operation. + * Success means clean merge; failure means conflicts that need resolution. + */ +export interface MergeResult { + /** 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; +} + +// ============================================================================= +// WorktreeManager Port Interface +// ============================================================================= + +/** + * WorktreeManager Port Interface + * + * Manages git worktrees for isolated agent workspaces. + * Each agent gets its own worktree to avoid file conflicts. + * + * This is the PORT - implementations (adapters) include: + * - GitWorktreeManager: Real git operations via CLI + * - MockWorktreeManager: In-memory for testing + * + * Covers requirements: + * - GIT-01: Create worktree for agent + * - GIT-02: List/get worktrees + * - GIT-03: Preview diff before merge + * - GIT-04: Merge worktree back and cleanup + */ +export interface WorktreeManager { + /** + * Create a new worktree for isolated agent work. + * + * Creates a new branch and worktree directory. + * The worktree will be ready for the agent to start working. + * + * @param id - Unique identifier for the worktree (usually agent/task ID) + * @param branch - Branch name to create + * @param baseBranch - Branch to base the new branch on (defaults to current branch) + * @returns The created worktree + * @throws If worktree creation fails (e.g., branch already exists) + */ + create(id: string, branch: string, baseBranch?: string): Promise; + + /** + * Remove a worktree and optionally its branch. + * + * Cleans up the worktree directory and removes it from git's tracking. + * Should be called after merge or when abandoning work. + * + * @param id - Worktree identifier + * @throws If worktree doesn't exist or removal fails + */ + remove(id: string): Promise; + + /** + * List all worktrees in the repository. + * + * Returns all worktrees including the main one. + * Useful for discovering active agent workspaces. + * + * @returns Array of all worktrees + */ + list(): Promise; + + /** + * Get a specific worktree by ID. + * + * @param id - Worktree identifier + * @returns The worktree if found, null otherwise + */ + get(id: string): Promise; + + /** + * Get the diff/changes in a worktree. + * + * Shows what files have changed compared to the base branch. + * Used for previewing before merge. + * + * @param id - Worktree identifier + * @returns Diff information + * @throws If worktree doesn't exist + */ + diff(id: string): Promise; + + /** + * Merge worktree changes into target branch. + * + * Attempts to merge the worktree's branch into the target branch. + * Returns conflict information if merge cannot be completed cleanly. + * + * @param id - Worktree identifier + * @param targetBranch - Branch to merge into (usually 'main' or 'integration') + * @returns Merge result with success status and any conflicts + * @throws If worktree doesn't exist + */ + merge(id: string, targetBranch: string): Promise; +}