diff --git a/agent-ops/rules/project/domain/cli/rules.md b/agent-ops/rules/project/domain/cli/rules.md index 785bb27..2ed61a7 100644 --- a/agent-ops/rules/project/domain/cli/rules.md +++ b/agent-ops/rules/project/domain/cli/rules.md @@ -2,51 +2,59 @@ ## 목적 / 책임 -사용자로부터 CLI 인자를 받아 파싱하고, `Application`을 통해 파이프라인 실행을 시작하는 진입 계층이다. +사용자로부터 CLI 인자를 받아 파싱하고, 콘솔 출력/스타일을 처리하며, `Application`을 통해 파이프라인 실행을 시작하는 진입 계층이다. 백그라운드 스케줄러의 상세 실행/등록 관리는 `scheduler` 도메인에서 담당한다. ## 포함 경로 - `lib/cli/cli.dart` — CLI 루트 객체, 출력/스타일 처리 +- `lib/cli/printer.dart` — OS별 콘솔 출력과 ANSI 스타일 처리 +- `lib/cli/cli_style.dart` — 콘솔 색상/스타일 enum - `lib/cli/commands/command_base.dart` — CLI 커맨드 공통 베이스 - `lib/cli/commands/command_manager.dart` — CLI 커맨드 라우팅 +- `lib/cli/commands/command_const.dart` — OS별 설치 경로 상수 - `lib/cli/commands/command_exe.dart` — `exe` 명령과 `Application.build()` 진입 - `lib/cli/commands/command_template.dart` — 템플릿 출력 -- `lib/cli/commands/command_start.dart` — 시작 커맨드 -- `lib/cli/commands/command_install.dart` — 설치 명령 +- `lib/cli/commands/command_start.dart` — 시작/중지 커맨드 +- `lib/cli/commands/command_install.dart` — 설치/제거 명령 - `lib/cli/commands/install/` — PATH 등록 등 설치 보조 로직 ## 제외 경로 - `lib/oto/` — 비즈니스 로직·파이프라인 엔진 (cli는 진입만 담당) +- `lib/cli/commands/command_scheduler.dart` — scheduler 명령 파싱과 등록/실행 진입점 (`scheduler` 도메인) - `lib/cli/commands/scheduler/` — 스케줄러 실행/등록/OS별 백그라운드 처리 (`scheduler` 도메인) ## 주요 구성 요소 - `CLI` (`cli.dart`) — CLI 루트 객체, 출력 유틸, `CLIConfig` -- `Printer` (`cli.dart`) — OS별 콘솔 출력 처리 +- `Printer` (`printer.dart`) — OS별 콘솔 출력 처리 +- `Color` / `Style` (`cli_style.dart`) — CLI 출력 스타일 enum - `CommandExe` — `-j`(Jenkins), `-t`(test), `-f`(file) 플래그 파싱 → `Application.build()` 호출 -- `CommandInstall` — PATH 등록 (`install/regist_path.dart`) -- `CommandStart` — 시작 커맨드 +- `IsolateExe` — `CommandExe`와 scheduler 실행에서 사용하는 isolate 진입 래퍼 +- `CommandInstall` / `CommandUninstall` — PATH 등록·해제 및 OS 시작 프로그램 설치 처리 +- `CommandStart` / `CommandStop` — 백그라운드 서비스 시작/중지 명령 표면 +- `CommandConstant` — OS별 설치 경로 계산 - `CommandTemplate` — 템플릿 출력 - `CommandManager` — CLI 커맨드 등록 관리 +- `RegistPath` — OS별 PATH 등록/해제 ## 유지할 패턴 - CLI 커맨드는 `CommandBase` 상속 - CLI는 인자 파싱과 진입점 역할만 수행하고, 파이프라인 실행은 `Application.build()`에 위임 - `CommandExe`는 `BuildType` 선택과 YAML 파일 읽기까지만 담당 -- 콘솔 출력은 `CLI.print*` 또는 `CommandBase` 출력 헬퍼를 사용 +- 콘솔 출력은 `CLI.print*`, `CLI.style`, `Printer`, 또는 `CommandBase` 출력 헬퍼를 사용 - CLI 변경 후 `dart analyze`를 실행하고, CLI 진입 변경이면 최소 `dart run bin/main.dart` 수준의 스모크 실행 가능 여부를 확인 ## 다른 도메인과의 경계 - **pipeline/command**: cli는 `Application.build()`만 호출. 파이프라인·커맨드 내부를 직접 참조하지 않는다 - **core**: DataComposer 호출은 Application 내부에서 이루어지며 cli는 관여하지 않는다 -- **scheduler**: `CommandScheduler`와 `lib/cli/commands/scheduler/**`는 scheduler 도메인이다. 일반 CLI 변경에서 scheduler 내부 동작을 함께 수정하지 않는다 +- **scheduler**: `CommandScheduler`, `lib/cli/commands/command_scheduler.dart`, `lib/cli/commands/scheduler/**`는 scheduler 도메인이다. 일반 CLI 변경에서 scheduler 내부 동작을 함께 수정하지 않는다 ## 금지 사항 - cli 레이어에서 Pipeline 또는 Command를 직접 인스턴스화하지 않는다 - 비즈니스 로직을 cli 커맨드 핸들러에 넣지 않는다 -- 일반 CLI 변경에 scheduler 등록 파일, 로그 파일, OS 시작 프로그램 로직을 섞지 않는다 +- 일반 CLI 변경에 scheduler 명령, 등록 파일, 로그 파일, OS 시작 프로그램 로직을 섞지 않는다 diff --git a/agent-ops/rules/project/domain/command/rules.md b/agent-ops/rules/project/domain/command/rules.md index 95bfe0a..4e5ce8b 100644 --- a/agent-ops/rules/project/domain/command/rules.md +++ b/agent-ops/rules/project/domain/command/rules.md @@ -19,8 +19,10 @@ - `Command` (`command.dart`) — 커맨드 베이스 클래스, `CommandType` enum - `CommandSpec` (`command.dart`) — CommandType → category/dataModel/samplePath 메타데이터 -- `CommandRegistry` (`command_registry.dart`) — CommandType → Command 매핑 등록소 +- `registerAllCommands()` (`command_registry.dart`) — 카테고리별 register 함수를 호출해 CommandType → Command 매핑 구성 +- `CommandRuntime` / `DefaultCommandRuntime` (`command_runtime.dart`) — 커맨드 외부 프로세스 실행 추상화 - `DataParam` (`base_data.dart`) — 모든 커맨드 파라미터의 베이스 +- `DataBuild` / `DataScheduler` (`command_data.dart`) — YAML 최상위 build/scheduler 데이터 - `DataCommand` (`command_data.dart`) — 모든 커맨드에 전달되는 통합 컨테이너 커맨드 카테고리와 우선 참조 파일: @@ -38,14 +40,14 @@ ## 유지할 패턴 -- 새 커맨드는 반드시 `Command` 상속 후 `CommandRegistry`에 등록 +- 새 커맨드는 반드시 `Command` 상속 후 카테고리별 `register*Command(s)()` 함수와 `registerAllCommands()` 경로에 등록 - `Command.register()`에는 `CommandSpec`을 함께 전달해 category, dataModel, samplePath를 기록 - 파라미터 모델은 `DataParam` 상속 + `@JsonSerializable` - `*.g.dart`는 `dart run build_runner build`로 생성한다. 생성 파일 직접 수정은 생성 불가한 긴급 상황에서만 한다 - `getWorkspace()`: workspace 필드 → `property['workspace']` → `commonData.workspace` 순으로 resolve - 커맨드 파라미터는 `getParam(command)`를 통해 태그 치환과 workspace resolve를 거친 뒤 `Data*` 모델로 파싱한다 - 결과 저장은 `<@property.key>` 형태의 쓰기 태그와 `setProperty()` / `complete()`의 `setResult`, `setExitCode` 흐름을 우선 사용한다 -- 외부 프로세스 실행은 기존 패턴인 `ProcessExecutor.start()` 또는 `ProcessExecutor.run()`을 우선 사용한다 +- 외부 프로세스 실행은 `Command.runtime`을 통해 `CommandRuntime.start()`, `run()`, `runExecutable()`, `startDetached()` 중 목적에 맞게 사용한다 - 커맨드 추가/파라미터 변경 시 관련 `assets/yaml/sample/**`와 README 커맨드 목록 갱신 필요 여부를 확인한다 - 데이터 모델 변경 후 `dart run build_runner build`와 `dart analyze`를 실행한다 @@ -60,6 +62,6 @@ - 커맨드에서 다른 커맨드를 직접 인스턴스화하거나 호출하지 않는다 - 흐름 제어(if/loop) 로직을 커맨드 내부에 넣지 않는다 -- `CommandRegistry` 외 장소에서 CommandType 매핑을 추가하지 않는다 +- 카테고리별 register 함수와 `registerAllCommands()` 경로 외 장소에서 CommandType 매핑을 추가하지 않는다 - 커맨드 구현 중 `Application.instance.dataCommandMap`을 직접 순회하거나 파이프라인 구조를 해석하지 않는다 - 샘플 YAML에 실제 토큰, 비밀번호, API 키를 넣지 않는다 diff --git a/agent-ops/rules/project/domain/core/rules.md b/agent-ops/rules/project/domain/core/rules.md index 252b6ac..b65bfe4 100644 --- a/agent-ops/rules/project/domain/core/rules.md +++ b/agent-ops/rules/project/domain/core/rules.md @@ -2,7 +2,7 @@ ## 목적 / 책임 -파이프라인 실행 전 단계에서 YAML 파싱, Jenkins 환경 변수 합성, 태그 치환을 담당하는 공통 인프라 레이어다. `Application` 싱글턴이 전체 빌드 흐름을 오케스트레이션한다. +파이프라인 실행 전 단계에서 YAML 파싱, Jenkins 환경 변수 합성, 태그 치환, 실행 컨텍스트 생성을 담당하는 공통 인프라 레이어다. `Application` 싱글턴이 전체 빌드 흐름을 오케스트레이션한다. 런타임 property, command state, build data 생성처럼 pipeline/command가 공유하는 실행 컨텍스트도 이 도메인에서 시작된다. ## 포함 경로 @@ -21,6 +21,9 @@ - `TagSystem` (`tag_system.dart`) — `` 읽기 / `<@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 진입점에 전달되는 빌드 성공/실패 결과 +- `SystemRuntime` / `DefaultSystemRuntime` (`system_runtime.dart`) — OS 환경·프로세스 실행 추상화 - `MattermostSender` / `MattermostData` (`utils/mattermost/`) — 공통 알림 헬퍼 - `Application` (`application.dart`) — build type 분기, command 등록, property 초기화, pipeline 실행 @@ -29,15 +32,16 @@ - 태그 치환은 반드시 `TagSystem`을 통해 처리 - 태그 전체 문자열이면 원본 타입 유지, 부분 삽입이면 `toString()` 변환 원칙 유지 - YAML 문자열 → Map 변환은 `Application.getMapFromYamlA()` 흐름을 유지 -- 커맨드 등록은 `registerAllCommands()` 호출 이후 pipeline validate를 수행 +- 커맨드 등록은 `registerAllCommands()` 호출 이후 command catalog validation과 pipeline validate를 수행 - property 기본값에 `workspace`가 없으면 `Application.current`를 채우는 흐름을 유지 +- 테스트 가능한 OS/프로세스 의존 로직은 `SystemRuntime`을 통해 주입 가능한 구조를 유지 - core 변경 후 `dart analyze`를 실행하고, 태그/파싱 변경이면 관련 단위 테스트 또는 최소 샘플 YAML 파싱 검증을 추가/확인한다 ## 다른 도메인과의 경계 - **pipeline**: DataComposer가 DataCommand 리스트 생성을 완료한 후 Pipeline이 실행 시작 - **command**: 커맨드 실행 중 쓰기 태그(`<@...>`) 처리는 TagSystem에 위임 -- **cli/scheduler**: build type, YAML content, scheduler build data는 cli/scheduler에서 넘기지만 실제 build 흐름은 Application이 담당 +- **cli/scheduler**: build type, YAML content, scheduler build data는 cli/scheduler에서 넘기지만 실제 build 흐름과 `BuildResult` 생성은 Application이 담당 - **sample**: 태그 문법이나 YAML 구조가 변경되면 sample 도메인의 YAML 예시를 함께 점검 ## 금지 사항 diff --git a/agent-ops/rules/project/domain/pipeline/rules.md b/agent-ops/rules/project/domain/pipeline/rules.md index 0c3cf5f..45e5027 100644 --- a/agent-ops/rules/project/domain/pipeline/rules.md +++ b/agent-ops/rules/project/domain/pipeline/rules.md @@ -17,20 +17,23 @@ YAML에서 파싱된 `DataCommand` 리스트를 순차 실행하고, 조건 분 ## 주요 구성 요소 - `Pipeline` — 커맨드 디스패치 루프 +- `PipelineValidateResult` — workflow 초기화/검증 결과와 실행 컨텍스트 보관 +- `PipelineExecutor` — 모든 pipeline 노드의 공통 베이스 - `PipelineExe` — 단일 커맨드 실행 핸들 +- `PipelineAsync` — 단일 커맨드 비동기 실행 핸들 - `PipelineExeHandle` — 실행 결과 처리 - `PipelineCondition` — 조건 평가 - `PipelineIf` / `PipelineSwitch` — 분기 흐름 - `PipelineForeach` / `PipelineWhile` — 반복 흐름 - `PipelineContain` — 중첩 파이프라인 -- `PipelineWaitUntil` — 대기 흐름 +- `PipelineWaitUntil` / `PipelineWaitUntilSeconds` — 조건 기반 또는 초 단위 대기 흐름 ## 유지할 패턴 - 파이프라인 노드는 단일 책임: 흐름 제어만 한다, I/O는 커맨드에 위임 - 새 흐름 제어 유형은 `Pipeline*` 네이밍으로 추가 - 새 흐름 제어 유형은 `Pipeline.exeMap`에 등록하고, 필요한 데이터 모델은 `lib/oto/data/pipeline_data.dart`에 둔다 -- 파이프라인 validate 단계에서 command ID 존재 여부와 하위 task 구조를 가능한 한 먼저 확인한다 +- 파이프라인 validate 단계에서 workflow task key, command ID 존재 여부, 하위 task 구조를 가능한 한 먼저 확인한다 - 조건식은 `PipelineCondition`의 type caster와 `Command.replaceTagValue()` 흐름을 유지한다 - pipeline 변경 후 `dart analyze`를 실행하고, if/foreach/while/switch/wait-until 중 영향을 받는 샘플 YAML 파싱 또는 실행 테스트를 확인한다 diff --git a/agent-ops/rules/project/rules.md b/agent-ops/rules/project/rules.md index 922d880..9bedca9 100644 --- a/agent-ops/rules/project/rules.md +++ b/agent-ops/rules/project/rules.md @@ -108,6 +108,7 @@ lib/ | `lib/oto/commands/**` | command | `agent-ops/rules/project/domain/command/rules.md` | | `lib/oto/data/**` | command | `agent-ops/rules/project/domain/command/rules.md` | | `lib/cli/commands/scheduler/**` | scheduler | `agent-ops/rules/project/domain/scheduler/rules.md` | +| `lib/cli/commands/command_scheduler.dart` | scheduler | `agent-ops/rules/project/domain/scheduler/rules.md` | | `lib/cli/**` | cli | `agent-ops/rules/project/domain/cli/rules.md` | | `lib/oto/application.dart` | core | `agent-ops/rules/project/domain/core/rules.md` | | `lib/oto/core/**` | core | `agent-ops/rules/project/domain/core/rules.md` |