import * as vscode from 'vscode';
import type { TransactionManager } from '../../core/transaction';
import type { ChatMessage } from '../../agent';

/**
 * `executeActions` 가 매 턴 새로 만드는 공유 컨텍스트. 모든 action handler 가
 * 같은 객체를 받아서 작업 결과를 누적 — 결과 텍스트 (`report`), brain 수정
 * 플래그, 첫 생성 파일 경로 등이 모두 여기 모인다.
 *
 * 모든 handler 는 같은 signature: `apply<Group>Actions(ctx: HandlerContext): Promise<void>`.
 * 반환값은 없음 — 결과는 ctx 객체에 *mutate* 로 누적된다 (배열 push, 콜백 호출).
 *
 * 왜 free function + ctx 패턴인가:
 *   - 15+ 종류의 action handler 가 transactionManager / report / chatHistory
 *     를 모두 공유. 매번 args 로 7-8개 던지면 호출부가 지저분해짐.
 *   - executeActions 의 try/catch 가 transactionManager.rollback() 을 책임지므로
 *     handler 들은 throw 만 잘 하면 됨 (FileSystemError 등).
 */
export interface HandlerContext {
    /** AI 가 한 턴에 내뱉은 raw text — handler 들이 자기 regex 로 자기 tag 만 추출. */
    aiMessage: string;
    /** 워크스페이스 루트 — validatePath() 로 sandbox 보장. */
    rootPath: string;
    /** 활성 brain 의 절대 디렉토리. brain 안 파일이면 brainModified 플래그 set. */
    activeBrainDir: string;
    /** Handler 들이 사용자에게 보일 결과 라인을 push 하는 곳. ex: "✅ Created: foo.ts". */
    report: string[];
    /** 일부 handler (read_file, list_files, read_brain, sheet_read, calendar) 는
     *  결과를 다음 턴의 컨텍스트에 주입하기 위해 internal system message 로 push. */
    chatHistory: ChatMessage[];
    /** brain 안 파일이 수정됐다고 표시 — executeActions 가 끝나서 자동 sync 결정. */
    markBrainModified: () => void;
    /** 새로 생성된 파일 절대경로를 기록 — executeActions 가 끝나서 editor 에 열기. */
    setFirstCreated: (absPath: string) => void;
    /** dry-run / commit / rollback 라이프사이클은 호출자(executeActions)가 책임.
     *  handler 들은 record() 만 호출 (state-changing action 시점에). */
    transactionManager: TransactionManager;
    /** vscode.ExtensionContext — feature module (calendar/sheets/tasks) 들이 OAuth
     *  토큰 등 secrets / globalState 에 접근할 때 필요. */
    context: vscode.ExtensionContext;
}
