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

domain	last_rule_review_commit	last_rule_updated_at
core	67d7b6e411	2026-06-01

core

목적 / 책임

파이프라인 실행 전 단계에서 YAML 파싱, Jenkins 환경 변수 합성, 태그 치환, 실행 컨텍스트 생성을 담당하는 공통 인프라 레이어다. Application 싱글턴이 전체 빌드 흐름을 오케스트레이션한다. 런타임 property, command state, build data 생성처럼 pipeline/command가 공유하는 실행 컨텍스트도 이 도메인에서 시작된다.

포함 경로

• apps/runner/lib/oto/application.dart — 싱글턴 오케스트레이터 (BuildType enum, 빌드 진입점)
• apps/runner/lib/oto/core/ — 태그 시스템, 데이터 합성, 정의 데이터
• apps/runner/lib/oto/utils/ — 공통 유틸리티 (Mattermost 등 재사용 헬퍼)
• apps/runner/assets/script/batch/jenkins_env_params.bat — Jenkins 환경 변수 합성에 쓰이는 Windows helper script
• apps/runner/assets/script/shell/jenkins_env_params.sh — Jenkins 환경 변수 합성 helper script

제외 경로

• apps/runner/lib/oto/pipeline/ — 실행 흐름 (core 처리 이후)
• apps/runner/lib/oto/commands/ — 커맨드 구현체 (core 결과물을 소비)
• apps/runner/lib/oto/agent/ — OTO Edge agent 설정/등록/통신 (agent 도메인)
• apps/runner/assets/script/의 빌드/패키징 보조 스크립트 — CLI/배포 보조 asset이며 core가 직접 해석하지 않는다

주요 구성 요소

• TagSystem (tag_system.dart) — <!namespace.key> 읽기 / <@namespace.key> 쓰기 태그 처리
• DataComposer (data_composer.dart) — YAML + Jenkins env → DataCommand 리스트 변환
• DefinedData (defined_data.dart) — 내장 YAML 템플릿 (빌트인 정의)
• ExecutionContext (execution_context.dart) — commonData, property, command state, command map 런타임 컨테이너
• BuildResult (build_result.dart) — CLI 진입점에 전달되는 빌드 성공/실패 결과
• YamlValidationResult (application.dart) — YAML 검증 CLI가 사용하는 구조화 검증 결과
• SystemRuntime / DefaultSystemRuntime (system_runtime.dart) — OS 환경·프로세스 실행 추상화
• MattermostSender / MattermostData (utils/mattermost/) — 공통 알림 헬퍼
• Application (application.dart) — build type 분기, command 등록, property 초기화, pipeline 실행

유지할 패턴

• 태그 치환은 반드시 TagSystem을 통해 처리
• 태그 전체 문자열이면 원본 타입 유지, 부분 삽입이면 toString() 변환 원칙 유지
• YAML 문자열 → Map 변환은 Application.getMapFromYamlA() 흐름을 유지
• 커맨드 등록은 registerAllCommands() 호출 이후 command catalog validation과 pipeline validate를 수행
• 실행 없는 YAML 검증은 Application.validateYamlContent()에서 build map, command list, command map, pipeline 초기화 순서로 확인한다
• property 기본값에 workspace가 없으면 Application.current를 채우는 흐름을 유지
• 테스트 가능한 OS/프로세스 의존 로직은 SystemRuntime을 통해 주입 가능한 구조를 유지
• Jenkins env helper script 변경 시 DataComposer의 호출 경로와 환경 변수 파싱 결과를 함께 확인한다
• core 변경 후 dart analyze를 실행하고, 태그/파싱 변경이면 관련 단위 테스트 또는 최소 샘플 YAML 파싱 검증을 추가/확인한다

다른 도메인과의 경계

• pipeline: DataComposer가 DataCommand 리스트 생성을 완료한 후 Pipeline이 실행 시작
• command: 커맨드 실행 중 쓰기 태그(<@...>) 처리는 TagSystem에 위임
• cli/scheduler: build type, YAML content, scheduler build data는 cli/scheduler에서 넘기지만 실제 build 흐름과 BuildResult 생성은 Application이 담당
• agent: agent config 파싱과 Edge 등록은 core가 아니라 agent 도메인이다. core의 YAML 파싱/검증 흐름과 agent bootstrap config를 섞지 않는다
• sample: 태그 문법이나 YAML 구조가 변경되면 sample 도메인의 YAML 예시를 함께 점검

금지 사항

• core에서 외부 시스템(Git, Jenkins API 등)을 직접 호출하지 않는다
• core에서 OTO Edge agent 등록 또는 proto socket 통신을 수행하지 않는다
• 커맨드별 파싱 로직을 DataComposer에 넣지 않는다
• pipeline 흐름 제어(if/foreach/switch 등)를 core에 넣지 않는다
• command별 실행 결과 처리 로직을 Application에 추가하지 않는다