toki/oto
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
oto/agent-ops/rules/project/domain/cli/rules.md

6.7 KiB
Raw Blame History

domain last_rule_review_commit last_rule_updated_at
cli 99cc06767f 2026-06-13

cli

목적 / 책임

사용자로부터 CLI 인자를 받아 파싱하고, 콘솔 출력/스타일을 처리하며, Application을 통해 파이프라인 실행을 시작하는 진입 계층이다. 백그라운드 스케줄러의 상세 실행/등록 관리는 scheduler 도메인에서 담당한다.

포함 경로

  • apps/runner/bin/main.dart — 외부 dart_framework 앱 래퍼를 통해 CLI를 초기화하는 실행 진입점
  • apps/runner/lib/cli/cli.dart — CLI 루트 객체, 출력/스타일 처리
  • apps/runner/lib/cli/printer.dart — OS별 콘솔 출력과 ANSI 스타일 처리
  • apps/runner/lib/cli/cli_style.dart — 콘솔 색상/스타일 enum
  • apps/runner/lib/cli/runner_output_adapter.dart — core RunnerOutputPort를 CLI 출력으로 연결하는 adapter
  • apps/runner/lib/cli/commands/command_base.dart — CLI 커맨드 공통 베이스
  • apps/runner/lib/cli/commands/command_manager.dart — CLI 커맨드 라우팅
  • apps/runner/lib/cli/commands/command_const.dart — OS별 설치 경로 상수
  • apps/runner/lib/cli/commands/command_exe.dart — exe 명령과 Application.build() 진입
  • apps/runner/lib/cli/commands/command_catalog.dart — 등록된 OTO 커맨드 catalog 출력 명령
  • apps/runner/lib/cli/commands/command_validate.dart — YAML 구조/의미 검증 명령
  • apps/runner/lib/cli/commands/command_template.dart — 템플릿 출력
  • apps/runner/lib/cli/commands/command_start.dart — 시작/중지 커맨드
  • apps/runner/lib/cli/commands/command_install.dart — 설치/제거 명령
  • apps/runner/lib/cli/commands/install/ — PATH 등록 등 설치 보조 로직
  • apps/runner/lib/resources.resource_importer.dart — 설치/패키징 asset용 resource_importer 생성 파일
  • apps/runner/assets/package/ — 배포/패키징 보조 파일
  • apps/runner/assets/bin/ — 설치 또는 패키징에 포함되는 보조 바이너리
  • apps/runner/assets/script/ — 빌드/패키징/실행 보조 스크립트. Jenkins env helper는 core 경계도 함께 확인

제외 경로

  • apps/runner/lib/oto/ — 비즈니스 로직·파이프라인 엔진 (cli는 진입만 담당)
  • apps/runner/lib/cli/commands/command_agent.dart — OTO Server runner agent 실행 명령 (agent 도메인)
  • apps/runner/lib/cli/commands/command_scheduler.dart — scheduler 명령 파싱과 등록/실행 진입점 (scheduler 도메인)
  • apps/runner/lib/cli/commands/scheduler/ — 스케줄러 실행/등록/OS별 백그라운드 처리 (scheduler 도메인)
  • apps/runner/lib/oto/agent/ — agent 설정, OTO Server 등록/job 통신, legacy iop Edge compatibility (agent 도메인)
  • apps/runner/lib/oto/core/output_port.dart — runner 출력 포트 추상화 (core 도메인)
  • apps/runner/assets/script/shell/oto_agent_bootstrap.sh — agent 설치/실행 bootstrap (agent 도메인)
  • apps/runner/assets/template/ — 커맨드 실행 중 사용하는 템플릿 (command 도메인)

주요 구성 요소

  • CLI (cli.dart) — CLI 루트 객체, 출력 유틸, CLIConfig
  • Printer (printer.dart) — OS별 콘솔 출력 처리
  • Color / Style (cli_style.dart) — CLI 출력 스타일 enum
  • CommandExe — -j(Jenkins), -t(test), -f(file) 플래그 파싱 → Application.build() 호출
  • IsolateExe — CommandExe와 scheduler 실행에서 사용하는 isolate 진입 래퍼
  • CommandCatalogCli — CommandCatalog를 사람이 읽는 표 또는 JSON으로 출력
  • CommandValidateCli — Application.validateYamlContent()를 통해 YAML을 실행 없이 검증
  • CommandInstall / CommandUninstall — PATH 등록·해제 및 OS 시작 프로그램 설치 처리
  • CommandStart / CommandStop — 백그라운드 서비스 시작/중지 명령 표면
  • CommandConstant — OS별 설치 경로 계산
  • CommandTemplate — 템플릿 출력
  • CommandManager — CLI 커맨드 등록 관리
  • RegistPath — OS별 PATH 등록/해제
  • CliRunnerOutputPort / setCliOutputLogHandler() — Application.build() 출력 포트를 CLI 출력과 log handler에 연결
  • apps/runner/bin/main.dart — CLI 초기화 시 등록할 top-level 명령 목록을 정의

유지할 패턴

  • CLI 커맨드는 CommandBase 상속
  • top-level 명령 등록은 apps/runner/bin/main.dart의 CLI.initialize(..., [Command...]) 목록에서 관리
  • CLI는 인자 파싱과 진입점 역할만 수행하고, 파이프라인 실행은 Application.build()에 위임
  • CommandExe는 BuildType 선택과 YAML 파일 읽기까지만 담당
  • catalog/validate처럼 JSON 출력을 지원하는 CLI는 stdout에 구조화 결과만 쓰고 일반 실행 로그는 억제한다
  • 콘솔 출력은 CLI.print*, CLI.style, Printer, 또는 CommandBase 출력 헬퍼를 사용
  • Application.build()에 CLI 출력을 연결할 때는 RunnerOutputPort를 직접 구현하지 말고 CliRunnerOutputPort adapter를 우선 사용한다.
  • CLI 변경 후 dart analyze를 실행하고, CLI 진입 변경이면 최소 dart run apps/runner/bin/main.dart 수준의 스모크 실행 가능 여부를 확인
  • 배포/설치 asset 변경 시 관련 CLI 설치/패키징 경로가 실제 파일명을 참조하는지 확인

다른 도메인과의 경계

  • pipeline/command: cli는 Application.build()만 호출. 파이프라인·커맨드 내부를 직접 참조하지 않는다
  • core: DataComposer 호출은 Application 내부에서 이루어지며 cli는 관여하지 않는다
  • core output: RunnerOutputPort 계약은 core 도메인이고, CLI 색상/출력으로 변환하는 adapter만 cli 도메인이다
  • agent: agent 명령과 CommandAgent는 agent 도메인이다. 일반 CLI 변경에서 OTO Server 등록/agent config 정책을 함께 수정하지 않는다
  • scheduler: CommandScheduler, apps/runner/lib/cli/commands/command_scheduler.dart, apps/runner/lib/cli/commands/scheduler/**는 scheduler 도메인이다. 일반 CLI 변경에서 scheduler 내부 동작을 함께 수정하지 않는다
  • framework: apps/runner/bin/main.dart는 외부 framework Application을 소비하지만 framework 의존성 자체는 framework 도메인에서 다룬다

금지 사항

  • cli 레이어에서 Pipeline 또는 Command를 직접 인스턴스화하지 않는다
  • 비즈니스 로직을 cli 커맨드 핸들러에 넣지 않는다
  • core RunnerOutputPort 계약 자체를 cli 도메인에서 변경하지 않는다
  • 일반 CLI 변경에 agent 등록, OTO Server/legacy Edge 연결, bootstrap 스크립트 정책을 섞지 않는다
  • 일반 CLI 변경에 scheduler 명령, 등록 파일, 로그 파일, OS 시작 프로그램 로직을 섞지 않는다