03-ssot — Tools

Status: ACTIVE AppliesTo: v10 ParentSSOT: skills/devian-core/03-ssot/SKILL.md

Scope

이 문서는 빌드 파이프라인, 검증, 워크스페이스 관련 SSOT를 정의한다.

중복 금지: 공통 용어/플레이스홀더/입력 분리/머지 규칙은 Root SSOT가 정본이며, 이 문서는 재정의하지 않는다.

Phase 모델

빌드는 4단계로 해석한다.

1. •Generate: 모든 산출물은 staging({tempDir})에만 생성
2. •Materialize: staging → module/upm/ts-modules로 clean + copy (모듈/패키지 단위)
3. •Validate: module/module과 upm의 완결성 검증
4. •Sync: upm → packageDir로 패키지 단위 동기화

staging({tempDir}) 외의 위치에 직접 생성하는 동작은 금지한다.

Generated Only 정책 (Hard Rule)

생성기(clean+generate)가 건드리는 영역은 오직 폴더명이 Generated인 디렉토리만 허용한다.

고정 유틸(수기 코드) 영역:

com.devian.foundation의 아래 폴더는 수기 코드로 유지하며, 생성기가 절대 clean/generate하지 않는다:

• •Runtime/Unity/_Shared/ — UnityMainThread, UnityMainThreadDispatcher
• •Runtime/Unity/Singletons/ — Singleton, SingletonRegistry, AutoSingleton, CompoSingleton
• •Runtime/Unity/Pool/ — IPoolable, IPoolFactory, PoolManager, Pool
• •Runtime/Unity/PoolFactories/ — InspectorPoolFactory, BundlePoolFactory
• •Runtime/Unity/AssetManager/ — AssetManager, DownloadManager (bootstrap/download utilities)
• •Runtime/Core/ — 순수 C# 코드 (UnityEngine 의존 없음)

레거시 경로 cleanup:

• •빌더는 기존 generated(소문자) 폴더가 존재하면 자동 제거
• •마이그레이션 완료 후 레포에 generated 폴더가 0개여야 함

TypeScript Workspace 정본 (Hard Rule)

• •TS 의존성 설치는 framework-ts/ 루트에서만 수행한다. (단일 node_modules)
• •workspace root는 framework-ts/package.json 단 하나만 허용한다.
• •lockfile은 framework-ts/package-lock.json 단 하나만 허용한다.

자세한 규칙: skills/devian/20-workspace

tsConfig 설정 (v10)

TS 산출물의 반영 위치를 관리하는 설정:

"tsConfig": {
  "moduleDir": "../framework-ts/module"
}

통합 모드 (기본):

• •generateDir를 생략하면 moduleDir을 생성 출력 루트로 사용
• •빌더는 moduleDir 하위에 staging 결과를 clean+copy

분리 모드 (선택):

• •generateDir를 moduleDir와 다른 경로로 명시하면 분리 모드
• •이 경우 moduleDir은 검증만, generateDir에만 clean+copy

Validate 단계 (Hard Rule)

C# 모듈 검증:

• •module (수동): 각 모듈에 .csproj 존재, "완벽한 C# 모듈"
• •module (생성): 각 모듈에 .csproj 존재, "완벽한 C# 모듈"

UPM 패키지 검증:

• •upm (수동): 각 패키지에 package.json 존재, 폴더명 == package.json.name
• •upm (생성): 각 패키지에 package.json 존재, 폴더명 == package.json.name

"완벽한 C# 모듈" = .csproj 존재 + ProjectReference 경로 유효 + dotnet build 가능

tempDir 경로 해석 및 분리 (Hard Rule)

{tempDir}는 실행한 입력 설정 JSON이 위치한 디렉토리 기준 상대경로로 해석된다.

빌더는 실행 시 {tempDir}를 clean(rm -rf) 후 재생성한다. 따라서:

• •동일 repo에서 서로 다른 입력 설정 JSON을 번갈아 실행하는 경우, tempDir을 공유하면 서로 staging을 삭제할 수 있으므로 tempDir 분리는 필수다.

Clean + Copy 정책

• •Copy 단계는 targetDir을 clean 후 copy한다.
• •충돌 방지 책임은 {buildInputJson} 설계(타겟 분리)에 있다.
  • •동일 targetDir에 여러 DomainKey/ProtocolGroup을 매핑하면, clean 단계 때문에 서로 덮어쓰거나 삭제될 수 있다.

디렉토리 역할 정의

공식 빌드 러너

공식 빌드 실행은 Node 기반 빌더를 사용한다: framework-ts/tools/builder/build.js

실행 예시: npm run builder -- ../{buildInputJson}

빌드 입력/설정/산출물

도메인/프로토콜 동적 빌드 정책 (입력 스펙, 설정 스펙, 산출물 규칙):

정책 문서: skills/devian-tools/20-build-domain

빌드 에러 리포팅

빌드 실패 시 에러 출력 규격 및 로그 파일 규칙:

정책 문서: skills/devian-tools/21-build-error-reporting

See Also

• •Root SSOT — 공통 용어/플레이스홀더/머지 규칙
• •Tools Policy
• •Workspace