oto/agent-ops/rules/project/domain/framework/rules.md

framework

목적 / 책임

oto_cli 전체에서 공유하는 런타임 인프라를 제공한다: 프로세스 실행, Isolate 관리, 로깅, 플랫폼 추상화, 공통 유틸리티.

포함 경로

• lib/framework/core/ — Application 베이스, AppDataManager (앱 메타데이터)
• lib/framework/data/ — Isolate 메시지 데이터 타입
• lib/framework/log/ — 로깅 시스템 (Log, LogItem, LogType)
• lib/framework/model/ — AppData 모델 및 JSON 직렬화
• lib/framework/platform/ — 플랫폼 추상화, IsolateManager, ProcessExecutor
• lib/framework/utils/ — 공통 유틸 (system_util, path, string_util, os_startup, Slack 헬퍼)

제외 경로

• lib/oto/ — OTO 비즈니스 로직 (framework 위에서 동작)
• lib/cli/ — CLI 레이어 (framework를 소비)

주요 구성 요소

• Application (core/application.dart) — runZonedGuarded 기반 앱 진입점 베이스
• AppDataManager (core/app_data_manager.dart) — 버전, Git hash, 빌드 일자 생성 및 app_data.json 저장
• IsolateManager / IsolateBase / IsolateHandler (platform/isolate_manager.dart) — Dart Isolate 라이프사이클 관리
• ProcessExecutor / ProcessData (platform/process.dart) — 셸 스크립트·외부 프로세스 실행 (macOS: zsh, Linux: bash, Windows: PowerShell)
• Log / LogItem (log/log.dart) — 로그 수집 및 파일 기록
• AppData (model/app_data.dart) — 앱 메타 모델 (app_data.json)
• system_util.dart — 환경 초기화, CLI 인자 파싱, YAML/JSON 파싱 헬퍼
• SlackSender / SlackData (utils/slack/) — Slack 메시지 전송 헬퍼

유지할 패턴

• 프로세스 실행은 ProcessExecutor.start() (스트리밍, stdout/stderr 실시간 수신) 또는 ProcessExecutor.run() (블로킹, 결과만 필요) 중 목적에 맞게 선택
• 로그 출력은 log() / logWarning() / logError() 함수를 통해서만 기록
• OS 분기가 필요한 코드는 Platform.isMacOS / isLinux / isWindows 조건으로 분기하고, 플랫폼별 구현은 platform_* 파일로 분리

다른 도메인과의 경계

• core: lib/oto/application.dart(OTO 오케스트레이터)는 framework의 Application을 상속하지 않고 독립 singleton. framework는 하위 인프라만 제공
• cli: scheduler_isolate.dart는 IsolateBase를 상속. framework가 API를 제공하고 cli가 소비
• command: 커맨드들이 ProcessExecutor를 직접 사용하여 셸 스크립트 실행

금지 사항

• framework 내부에서 lib/oto/ 또는 lib/cli/를 import하지 않는다 (단방향 의존성 유지)
• OTO 비즈니스 로직(파이프라인, 커맨드 등록 등)을 framework에 넣지 않는다
• ProcessExecutor를 우회하여 dart:io Process를 직접 호출하지 않는다