---
domain: core
last_rule_review_commit: 810532a097c1309cd28d7130d8a33bcc779c96e4
last_rule_updated_at: 2026-06-24
---

# core

## 목적 / 책임

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

## 포함 경로

- `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 Server runner agent 설정/등록/remote job 통신 (`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 진입점에 전달되는 빌드 성공/실패 결과
- `BuildArtifact` (`build_result.dart`) — remote consumer에 보고할 artifact 선언 metadata
- `RunnerOutputPort` / `RunnerOutputStyle` / `NoopRunnerOutputPort` (`output_port.dart`) — CLI/agent가 교체할 수 있는 runner 출력 포트 계약
- `StepEvent` (`execution_context.dart`) — pipeline step started/completed/failed event 직렬화 모델
- `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`를 채우는 흐름을 유지
- `Application.build()` 시작 시 `ExecutionContext.output`, step event, command map, command state를 새 실행 단위에 맞게 초기화한다
- `BuildResult`는 `ExecutionContext.stepEvents`와 전달받은 artifact 선언을 복사해서 반환한다
- 출력은 직접 `print`를 추가하기보다 `RunnerOutputPort` 또는 기존 `Application.log()` 경로를 사용한다
- 테스트 가능한 OS/프로세스 의존 로직은 `SystemRuntime`을 통해 주입 가능한 구조를 유지
- Jenkins env helper script 변경 시 `DataComposer`의 호출 경로와 환경 변수 파싱 결과를 함께 확인한다
- core 변경 후 `dart analyze`를 실행하고, 태그/파싱 변경이면 관련 단위 테스트 또는 최소 샘플 YAML 파싱 검증을 추가/확인한다

## 다른 도메인과의 경계

- **pipeline**: DataComposer가 DataCommand 리스트 생성을 완료한 후 Pipeline이 실행 시작
- **pipeline events**: pipeline은 step event를 기록하지만 event 모델과 저장 위치는 core `ExecutionContext`다
- **command**: 커맨드 실행 중 쓰기 태그(`<@...>`) 처리는 TagSystem에 위임
- **cli/scheduler**: build type, YAML content, scheduler build data는 cli/scheduler에서 넘기지만 실제 build 흐름과 `BuildResult` 생성은 Application이 담당
- **cli output**: CLI 색상/출력 adapter는 cli 도메인이고, output port interface는 core 도메인이다
- **agent**: agent config 파싱, OTO Server 등록, remote job claim/report는 core가 아니라 agent 도메인이다. core의 YAML 파싱/검증 흐름과 agent bootstrap config를 섞지 않는다
- **sample**: 태그 문법이나 YAML 구조가 변경되면 sample 도메인의 YAML 예시를 함께 점검

## 금지 사항

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