@litmers/cursorflow-orchestrator 0.1.40 → 0.2.2

package/dist/core/git-lifecycle-manager.d.ts

@@ -0,0 +1,284 @@
+/**
+ * Git Lifecycle Manager
+ *
+ * Git 파이프라인의 생명주기를 명확하게 관리합니다.
+ *
+ * 작업 흐름:
+ * 1. 작업 시작 (startWork): 브랜치 생성 및 체크아웃
+ * 2. 작업 중 (saveProgress): 주기적 커밋 (선택적)
+ * 3. 작업 종료 (finalizeWork): 남은 변경사항 커밋 및 푸시
+ * 4. 머지 (mergeToTarget): 다음 단계로 머지
+ *
+ * 생명주기 상태:
+ * - IDLE: 초기 상태 / 작업 종료 후
+ * - PREPARING: 브랜치 준비 중
+ * - WORKING: 작업 진행 중
+ * - COMMITTING: 커밋 중
+ * - PUSHING: 푸시 중
+ * - MERGING: 머지 중
+ * - ERROR: 오류 발생
+ */
+/**
+ * Git 작업 생명주기 상태
+ */
+export declare enum GitLifecyclePhase {
+    /** 대기 상태 */
+    IDLE = "IDLE",
+    /** 브랜치/워크트리 준비 중 */
+    PREPARING = "PREPARING",
+    /** 작업 진행 중 */
+    WORKING = "WORKING",
+    /** 커밋 중 */
+    COMMITTING = "COMMITTING",
+    /** 푸시 중 */
+    PUSHING = "PUSHING",
+    /** 머지 중 */
+    MERGING = "MERGING",
+    /** 오류 발생 */
+    ERROR = "ERROR"
+}
+/**
+ * 브랜치 유형
+ */
+export declare enum BranchType {
+    /** Pipeline 브랜치 (Lane당 하나) */
+    PIPELINE = "pipeline",
+    /** Task 브랜치 (Task당 하나) */
+    TASK = "task",
+    /** Flow 브랜치 (최종 결과) */
+    FLOW = "flow"
+}
+/**
+ * 작업 시작 옵션
+ */
+export interface StartWorkOptions {
+    /** 워크트리 디렉토리 */
+    worktreeDir: string;
+    /** 생성할 브랜치 이름 */
+    branchName: string;
+    /** 베이스 브랜치 */
+    baseBranch: string;
+    /** Repository 루트 */
+    repoRoot: string;
+    /** Lane 이름 (로깅용) */
+    laneName?: string;
+    /** Task 이름 (로깅용) */
+    taskName?: string;
+    /** 브랜치 유형 */
+    branchType?: BranchType;
+    /** 의존성 브랜치들 (머지할 브랜치들) */
+    dependencyBranches?: string[];
+}
+/**
+ * 작업 종료 옵션
+ */
+export interface FinalizeWorkOptions {
+    /** 워크트리 디렉토리 */
+    worktreeDir: string;
+    /** 현재 브랜치 이름 */
+    branchName: string;
+    /** 커밋 메시지 */
+    commitMessage?: string;
+    /** Lane 이름 (로깅용) */
+    laneName?: string;
+    /** Task 이름 (로깅용) */
+    taskName?: string;
+    /** 푸시 여부 (기본: true) */
+    push?: boolean;
+    /** 원격 이름 (기본: origin) */
+    remote?: string;
+    /** 변경사항 없으면 스킵 */
+    skipIfClean?: boolean;
+}
+/**
+ * 머지 옵션
+ */
+export interface MergeOptions {
+    /** 워크트리 디렉토리 */
+    worktreeDir: string;
+    /** 소스 브랜치 */
+    sourceBranch: string;
+    /** 타겟 브랜치 */
+    targetBranch: string;
+    /** 커밋 메시지 */
+    commitMessage?: string;
+    /** Lane 이름 (로깅용) */
+    laneName?: string;
+    /** 머지 유형 */
+    mergeType?: 'task_to_pipeline' | 'dependency' | 'final';
+    /** 충돌 시 중단 */
+    abortOnConflict?: boolean;
+    /** 푸시 여부 */
+    push?: boolean;
+}
+/**
+ * 작업 결과
+ */
+export interface GitOperationResult {
+    /** 성공 여부 */
+    success: boolean;
+    /** 오류 메시지 */
+    error?: string;
+    /** 생성된 커밋 해시 */
+    commitHash?: string;
+    /** 변경된 파일 수 */
+    filesChanged?: number;
+    /** 추가 정보 */
+    details?: Record<string, any>;
+}
+/**
+ * Lane별 Git 상태 추적
+ */
+interface LaneGitState {
+    laneName: string;
+    phase: GitLifecyclePhase;
+    currentBranch: string | null;
+    pipelineBranch: string | null;
+    worktreeDir: string | null;
+    lastCommitHash: string | null;
+    uncommittedChanges: boolean;
+    lastOperation: string | null;
+    lastOperationTime: number | null;
+    error: string | null;
+}
+/**
+ * Git 파이프라인 생명주기 관리자
+ *
+ * 사용 예:
+ * ```typescript
+ * const gitManager = GitLifecycleManager.getInstance();
+ *
+ * // 1. 작업 시작
+ * await gitManager.startWork({
+ *   worktreeDir: '/path/to/worktree',
+ *   branchName: 'cursorflow/task-1',
+ *   baseBranch: 'main',
+ *   repoRoot: '/path/to/repo',
+ *   laneName: 'lane-1'
+ * });
+ *
+ * // 2. 작업 진행...
+ *
+ * // 3. 작업 종료 (모든 변경사항 커밋 및 푸시)
+ * await gitManager.finalizeWork({
+ *   worktreeDir: '/path/to/worktree',
+ *   branchName: 'cursorflow/task-1',
+ *   commitMessage: 'feat: implement feature',
+ *   laneName: 'lane-1'
+ * });
+ *
+ * // 4. 파이프라인 브랜치로 머지
+ * await gitManager.mergeToTarget({
+ *   worktreeDir: '/path/to/worktree',
+ *   sourceBranch: 'cursorflow/task-1',
+ *   targetBranch: 'cursorflow/pipeline',
+ *   laneName: 'lane-1',
+ *   mergeType: 'task_to_pipeline'
+ * });
+ * ```
+ */
+export declare class GitLifecycleManager {
+    private static instance;
+    /** Lane별 상태 추적 */
+    private laneStates;
+    /** 디버그 모드 */
+    private verbose;
+    private constructor();
+    /**
+     * 싱글톤 인스턴스 획득
+     */
+    static getInstance(): GitLifecycleManager;
+    /**
+     * 인스턴스 리셋 (테스트용)
+     */
+    static resetInstance(): void;
+    /**
+     * Lane의 Git 상태 초기화
+     */
+    initializeLane(laneName: string, pipelineBranch: string, worktreeDir?: string): void;
+    /**
+     * Lane의 Git 상태 조회
+     */
+    getLaneState(laneName: string): LaneGitState | undefined;
+    /**
+     * Lane 상태 업데이트
+     */
+    private updateLaneState;
+    /**
+     * 작업 시작 - 브랜치 생성 및 체크아웃
+     *
+     * 1. 워크트리가 없으면 생성
+     * 2. 브랜치가 없으면 baseBranch에서 생성
+     * 3. 의존성 브랜치들 머지 (있는 경우)
+     * 4. 브랜치 체크아웃
+     */
+    startWork(options: StartWorkOptions): Promise<GitOperationResult>;
+    /**
+     * 워크트리 확인 및 생성
+     */
+    private ensureWorktree;
+    /**
+     * 의존성 브랜치 머지
+     */
+    private mergeDependencyBranch;
+    /**
+     * 진행 상황 저장 (중간 커밋)
+     *
+     * 장기 작업 중 주기적으로 호출하여 진행 상황을 저장할 수 있습니다.
+     */
+    saveProgress(worktreeDir: string, message: string, laneName?: string): Promise<GitOperationResult>;
+    /**
+     * 작업 종료 - 모든 변경사항 커밋 및 푸시
+     *
+     * 1. 남은 변경사항 모두 스테이징
+     * 2. 커밋 생성
+     * 3. 원격으로 푸시
+     */
+    finalizeWork(options: FinalizeWorkOptions): Promise<GitOperationResult>;
+    /**
+     * 타겟 브랜치로 머지
+     *
+     * 사용 사례:
+     * - Task → Pipeline 머지
+     * - 의존성 브랜치 머지
+     * - 최종 Flow 브랜치 생성
+     */
+    mergeToTarget(options: MergeOptions): Promise<GitOperationResult>;
+    /**
+     * 워크트리 정리
+     */
+    cleanupWorktree(worktreeDir: string, laneName?: string): Promise<GitOperationResult>;
+    /**
+     * Lane 상태 정리
+     */
+    cleanupLane(laneName: string): void;
+    /**
+     * 현재 브랜치에 미커밋 변경사항이 있는지 확인
+     */
+    hasUncommittedChanges(worktreeDir: string): boolean;
+    /**
+     * 안전하게 모든 변경사항 커밋 (오류 무시)
+     */
+    safeCommitAll(worktreeDir: string, message: string, laneName?: string): Promise<GitOperationResult>;
+    /**
+     * 브랜치가 원격에 존재하는지 확인
+     */
+    branchExistsRemote(branchName: string, worktreeDir: string): boolean;
+    /**
+     * 로깅 헬퍼
+     */
+    private log;
+    /**
+     * 디버그 모드 설정
+     */
+    setVerbose(verbose: boolean): void;
+}
+/**
+ * 싱글톤 인스턴스 획득
+ */
+export declare function getGitLifecycleManager(): GitLifecycleManager;
+/**
+ * 인스턴스 리셋 (테스트용)
+ */
+export declare function resetGitLifecycleManager(): void;
+export {};