Codewalkers/src/git/types.ts

/**
 * 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<Worktree>;

  /**
   * 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<void>;

  /**
   * 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<Worktree[]>;

  /**
   * Get a specific worktree by ID.
   *
   * @param id - Worktree identifier
   * @returns The worktree if found, null otherwise
   */
  get(id: string): Promise<Worktree | null>;

  /**
   * 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<WorktreeDiff>;

  /**
   * 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<MergeResult>;
}